[Owncloud] Documentation Repo Howto

[Daniel Molkentin]

Hi,

I realized I never really introduced our documentation repository, sorry for that. This mail tries to fix this as I see a lot of movement again in the documentation repo. It is changing almost every hour now, which is really awesome. I want to take the opportunity to , we have two branches to work on on the server, master and stable45. The naming conventions follow the ones in core and apps.

All documentation that concerns both 4.5 and master should go into stable45 and will be merged into master regulary. Everything that only concerns master should only be documented in master for 5.0. However, this does not mean a free ticket to abandon stable45.

I know that for most of us the only thing less rewarding than documentation is documenting what many of you see as 'yesterdays software', but this is what people use, and should be using. So please help them.

To help matters, I propose the following commit policy for the documentation repository:

- Please push only after running at least "make html", indeally also "make latexpdf" ran locally without problems.
- If you broke it, you will receive mail from Mr. Jenkins. If you are unsure how to fix it, get in touch with me
- Only commit to master if you have documented the same in stable45 or the feature didn't exist in 4.5, do so by merging (stable-first approach)
- Exceptions are in place for GCI. Please get in touch with me. I will do the painful merging
- If you document something in stable45, you are responsible for landing it in master through merging. If you are unsure how to do that, please get in touch with me.
- I will also take care of documentation created through PRs.

FAQ:

Q: What should I look at as a reference for good documentation style?
A: The Sphinx documentation (http://sphinx-doc.org/contents.html) itself is very good. Every page has a "Show source" section that shows how it was made.

Q: For my topic, should I create topic.rst or topic/index.rst?

A: Do not create a directory. We can still refactor into a directory later on. If you sit on top of a huge pile of documentation on a single topic, I am glad to assist you with your luxury problem :-)

Q: Why not use cherry-picking from master to stable45?

A:  Cherry-picking only works if we have someone who makes sure the cherrys actually get picked. This also involves adjusting the documentation to stable45, which requires domain specific knowledge of both versions. If you still would like to volunteer, speak up.

Q: This doesn't look like a documentation at all, it doesn't even have an introduction and a proper structure!

A: Yes, I know. Working on that. Volunteers welcome.

Q: LaTeX barfs on my fancy table. What can I do to fix this?

A: Avoid overly complex tables. Complex tables should usually broken down into simple tables + text anyway. Remember, people might read this on their eBook reader! Everything with multiline columns is something that the latex generator frowns upon. In general though, the latex generator is just a lot more picky over a broken ascii table art misplacement than the HTML equivalent is. Double-check your markup.

Cheers,
  Daniel

--
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/20121128/cab0f36e/attachment.html>