[Owncloud] Moving Documentation - Volunteers wanted

[Daniel Molkentin]

Hi,

(tl;dr summary below)

at the devsprint meeting in Berlin, we introduced a new documentation system based on Sphinx [1], This uses reStructuredText[2] (witjh Sphinx extensions [3]), a markup language markdown, but more expressive, which also GitHub understands (and will render on the fly).

I have created a documentation repo in GitHub [4] which contains 3 books (manuals):

- Admin: Everything related to server administration and security goes here
- Developer: Everything related to developing apps FOR ownCloud as well as developing ownCloud ITSELF goes here. If it reaches a considerable volume, we might split it in two.
- User: Everything that concerns the end user, i.e. mostly WebUI documentation.

If you want to check it out and build html from it, simply follow the README. The desktop client has a documentation in its own repository [5], since it has independent release cycles. We can do similar things for the Android client.

Now here is why we chose this over the WordPress approach:

- everyone can contribute via GitHub and Merge Requests.
- GitHub gives everyone the ability to edit without checking out (and a preview functionality for most of the markup), making trivial changes simple (we will create a link from every page to the GitHub repo)
- Thanks to Sphinx we can export this not only to HTML, but also to PDF or eBook formats (and many more!)
- Sphinx is designed for creating books. Let's use it to create comprehensive and consistent documentation!
- Versioning: Finally we will be able to branch the documentation with every server release, so everyone will know
  which server version the documentations is actually talking about!

So here is how I think we should approach this: We need to skim through the existing dev [7] and support [8] documentation and

- check if its still applicable
- bring outdated articles up to date
- fit it into either category (dev, admin, user) or even if it belongs into the client doc
- create a articles/chapters
- create a merge request or submit directly

We need some way of coordination, so I suggest denoting every URL that you have moved into the repository
to the pad at [9]. The syntax is [URL on webserver] -> [URL to rst file in github].

The new documentation repository will be licensed CC-BY Unported 3.0 [9] (I'll put a note in the repository). I have tried to track down all contributors to the existing docs in WordPress who are not employed by ownCloud Inc. They have been notified and agreed to the release under this license. Should I have missed someone, despite best efforts, please speak up and reply to me privately.

If you want to volunteer, please add the urls on the ownCloud.org page to the pad [9]. and add your name.

Tom (tpn on freenode) and I (danimo on freenode) will assume the roles of editors in chief for the time being and will help out where needed.

Cheers,
  Daniel

PS: Yes, we will bring this online ASAP, but currently we are still sorting out some things. I'll post an update once this has happened. http://daniel.molkentin.de/occ/ is an example for the default HTML output (client manual), but thanks to Bernhard Posselt we already have a native-looking theme for owncloud.org.

tl;dr: Documentation will be awesome, but only if _you_ volunteer. If everyone contributes a bit, we will sort this out in no time. Please help us! Entrance barriers are super low: Clone [4] today (or edit directly at GibHub in your browser!), discuss on IRC and coordinate at [8].

[1] http://sphinx.pocoo.org/

[2] http://docutils.sourceforge.net/rst.html#reference-documentation
[3] http://sphinx-doc.org/markup/index.html

[4] https://github.com/owncloud/documentation
[5] https://github.com/owncloud/mirall/tree/master/doc

[7] http://owncloud.org/dev
[6] http://owncloud.org/support

[8] http://piratepad.net/kIUcbF5yGq

[9] http://creativecommons.org/licenses/by/3.0/
--
www.owncloud.com - Your Data, Your Cloud, Your Way!

ownCloud GmbH, GF: Markus Rex, Holger Dyroff
Schloßäckerstrasse 26a, 90443 Nürnberg, HRB 28050 (AG Nürnberg)

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/owncloud/attachments/20121105/bdd71fa9/attachment.html>