[Owncloud] Documentation Repo Howto

[Qingping Hou]

Hi Daniel,

Can I move the policy you mentioned in the mail to developer document?
It might be helpful for other volunteers who missed this mail ;p


On Wed, Nov 28, 2012 at 2:29 PM, Daniel Molkentin <danimo at owncloud.com> wrote:
> 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)
>
>
> _______________________________________________
> Owncloud mailing list
> Owncloud at kde.org
> https://mail.kde.org/mailman/listinfo/owncloud
>