+1, also a clearer Wiki to show how to contribute towards docs would be good, including what repo to fetch - I assume this would be made easier using Github Pull requests?
On the Wiki: GIT Usage - with Examples Conventional Markup (Linking to documentation can be daunting to some users, causing them not to contribute - as with the case with Publican) Marty On Tue, Dec 10, 2013 at 5:36 PM, Francois Gaudreault < fgaudrea...@cloudops.com> wrote: > +1. Anything to move away from "manual" docbook is good!!! Now we won't > have any reasons not to update the documentation if we find bugs in it :S > > asciidoc would have been another possibility tho... but reST is fine :) > > Francois > > > On Tue, Dec 10, 2013 at 12:23 PM, Animesh Chaturvedi < > animesh.chaturv...@citrix.com> wrote: > > > > > > > -----Original Message----- > > From: Sebastien Goasguen [mailto:run...@gmail.com] > > Sent: Monday, December 09, 2013 11:31 PM > > To: dev@cloudstack.apache.org > > Cc: Radhika Puthiyetath; msweet....@gmail.com; Mike Tutkowski > > Subject: Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs > > > > > > On Dec 9, 2013, at 9:37 PM, Animesh Chaturvedi < > > animesh.chaturv...@citrix.com> wrote: > > > > > I am +1 to make documentation easier but we just passed code freeze for > > 4.3 and I feel we need to do it after 4.3. > > > > > > > docs are not in the 4.3 code branch. it's different releases... > > > > Animesh> But they will be released together. > > > > > > > > Animesh > > > > > > -----Original Message----- > > > From: sebgoa [mailto:run...@gmail.com] > > > Sent: Monday, December 09, 2013 3:54 AM > > > To: dev@cloudstack.apache.org > > > Cc: Radhika Puthiyetath; msweet....@gmail.com; Mike Tutkowski > > > Subject: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs > > > > > > Hi, > > > > > > There has been lots of discussion about docs over the last 3/4 months, > > in summary the issues are: > > > > > > -Difficult to maintain and keep website up to date (issues with lang > and > > issues with pdf formatting lately) -Difficult to contribute to easily, > > docbook is fine but tedious to work on. > > > -Errors in the docs don't get properly fixed -Mix of OS information > > -Lack of content for certain features -Docs release cycle. Docs have bugs > > that will never get fixed in that specific release (because we see it as > > code release) > > > > > > To remedy some of those issues and work on a new release process > > specific to docs we moved the docs to its own repo: > > > > > > https://git-wip-us.apache.org/repos/asf?p=cloudstack-docs.git > > > > > > *I propose that we move away from docbook and use a more readable > > format: restructuredtext* > > > > > > I have worked on a prototype that uses restructured text: > > > http://docutils.sourceforge.net/rst.html > > > > > > This format makes it extremely easy to write docs. Existing docbook > > content could be converted to .rst using a tool like pandoc: > > > http://johnmacfarlane.net/pandoc/ > > > > > > *In addition to changing the format I propose that we use > > readthedocs.org* > > > > > > This will help with the release and build of the docs. readthedocs > grabs > > the docs from a git repo, builds html, pdf and epub. > > > It can also maintain several releases. We can apply a specific -theme- > > to our docs. > > > > > > See a prototype here: > > > > > > http://cloudstack.readthedocs.org/en/latest/ > > > > > > *I propose that we move to this as early as 4.3 documentation* > > > > > > Assuming this proposal passes, we would need to: > > > > > > -re-architect the repo > > > -create the proper cnames to be in accordance with trademark guidelines > > -we can decide what content to keep or not and convert what we keep. > > > -decide how we organize the content > > > -start accepting pull requests (noting that pages can be edited > directly > > from github) -make a first release of this new doc site at the same time > > than 4.3 release. > > > > > > > > > Thoughts, flames ? > > > > > > > > > -Sebastien > > > > >
