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
