Maybe this should also be worked into the documentation so we have documentation about the how to produce the documentation in the documentation :)
On 11/28/2012 08:29 PM, Daniel Molkentin 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@kde.org > https://mail.kde.org/mailman/listinfo/owncloud _______________________________________________ Owncloud mailing list Owncloud@kde.org https://mail.kde.org/mailman/listinfo/owncloud
