> -----Original Message----- > From: Wido den Hollander [mailto:w...@widodh.nl] > Sent: Wednesday, August 08, 2012 2:10 PM > To: cloudstack-dev@incubator.apache.org > Subject: Writing documentation, where? > > Hi, > > Chip's e-mail about the 4.0 release woke me up, I still had to write some > documentation... > > For 2.2 and 3.0.2 there is a Installation Guide, but where did that come > from? (What source) Are we going to maintain it for 4.0? > > In the repository there is /docs and I guess that is the right place? > These are all DocBook XML files, but I can't find a Ant target for it? > > How do I turn these XML files into viewable HTML files so I can verify > them? > > Is this the place to document everything or are we going to maintain a > Wiki? > > I want to update the documentation about configuring/adding a Hypervisor > host, the system requirements, using RBD and probably other stuff I'll find > along the way. > > This is just one of the dots I'm still haven't connected. > > Wido >
Short answer: Please see https://cwiki.apache.org/confluence/display/CLOUDSTACK/CloudStack+Documentation+Contributors+Overview. Also see the README file in the docs directory of the repo -- which I've just noticed didn't get checked in when we moved docs into the Apache repo -- I'll fix ASAP !! Meanwhile, I've pasted the text below. Long answer: (1) Wido, funny you asked, I was just working on an "all about docs" email to send to my employers later today. Enjoy! *Apache Transition* We are beginning to position CloudStack docs for success in Apache: adopting open source tools, moving into a source-controlled format, and making it possible to collaborate. Check out our Doc Contributor's Overview<https://cwiki.apache.org/confluence/display/CLOUDSTACK/CloudStack+Documentation+Contributors+Overview>. We are moving our documentation out of Microsoft Word, which was used for the Citrix-owned releases up to 3.0.3. Setting up all-new infrastructure and converting our legacy content is a major undertaking. We have moved the former Admin Guide and are in process of moving the Install Guides. We will need help rewriting Installation for Apache CloudStack 4.0 (see a separate email!). Our efforts so far have paid off. The main docs writers (Jessica, Radhika) are now able to collaborate effectively across time zones. Other community members are beginning to submit doc patches and do doc reviews. Just as with code, partners should be able to use the Apache repo as their “upstream” and create commercial versions of docs based on our files. *Conferences and Networking* I attended OSCON last month and met the writers from OpenStack, Eucalyptus, Apache, and Libre Office. From those conversations, it seems CloudStack is already off to a good start with our choice of doc tools and publication strategy. We should continue to develop those relationships. Due to travel restrictions at my employer, I won’t attend OpenHelp in Cincinnati this weekend -- it’s the one conference that focuses on open-source documentation. That’s a missed opportunity. I will try to attend next year. If anyone else in the CloudStack community is positioned to attend, that would be great. *Resources* Radhika PC joined us at the end of April, thereby doubling the size of the team dedicated full-time to CloudStack documentation. It's our hope that we will also gain many more doc contributors and reviewers from the Apache community. *Plans* At the Documentation Team page<https://cwiki.apache.org/confluence/display/CLOUDSTACK/Documentation+Team>, you can find doc how-tos and notes on various interesting projects we are developing. Here is where we'll need to develop our doc plan for Apache CloudStack 4.0. Our major goal now: to be in a position to give a killer talk at the STC conference in Bangalore this fall and at OpenHelp next year. (2) The README file that didn't get copied over yet is pasted below. Of course, we can discuss and amend this if needed: Author: Jessica Tomechak Updated: June 26, 2012 ------------------------------------------- WHAT'S IN THIS REPOSITORY: WORK IN PROGRESS ------------------------------------------- This repository contains the source files for CloudStack documentation. The files are currently incomplete as we are in the process of converting documentation from an outdated file format into XML files for this repo. The complete documentation can be seen at docs.cloudstack.org. ---------------------------------- DOCUMENTATION SUBDIRECTORIES ---------------------------------- United States English language source files are in the en-US subdirectory. Additional language subdirectories can be added. Each file in a language subdirectory contains one chunk of information that may be termed a section, module, or topic. The files are written in Docbook XML, using the Docbook version and tag supported by the Publican open-source documentation tool. ---------------------------------- VALID XML TAGS ---------------------------------- Certain tags are disallowed by Publican. Please consult their documentation for more details. http://jfearn.fedorapeople.org/en-US/Publican/2.7/html/Users_Guide/ ---------------------------------- SECTIONS, CHAPTERS, AND BOOK FILES ---------------------------------- The files for every topic and audience are in a single directory. The content is not divided into separate subdirectories for each book, or separate repositories for each book. Therefore, the content can be flexibly and easily re-used. Each file represents a single section that can be assembled with other sections to build any desired set of information. These files contain <section> ... </section> tags. Some of the XML files contain only a series of include tags to pull in content from other files. Such an "include file" is either a major section, a chapter in a book, or the master book file. A chapter contains <chapter> ... </chapter> tags. The master book file contains <book> ... </book> tags. This file is referred to in the Publican configuration file, and is used as the controlling file when building the book. As a naming convention, start the name of a book file with cloudstack_ ; for example, cloudstack_installation. A Publican book file must also have certain other tags that are expected by Publican when it builds the project. Copy an existing master book file to get these tags. ---------------------------------- CONFIG FILES ---------------------------------- For each book file, there must be a corresponding publican.cfg (or <other_name>.cfg) file in order to build the book with Publican. The docname: attribute in the config file matches the name of the master book file; for example, docname: cloudstack corresponds to the master book file cloudstack.xml. The .cfg files reside in the main directory, docs. To build a different book, just use the Publican command line flag --config=<filename>.cfg. ---------------------------------- TO BUILD A BOOK ---------------------------------- We will set up an automatic Publican job that generates new output whenever we check in changes to this repository. You can also build a book locally as follows. First, install Publican, and get a local copy of the book source files. Put the desired publican.cfg in the docs directory. Go to the command line, cd to that directory, and run the publican build command. Specify what output format(s) and what language(s) you want to build. Always start with a test run. For example: publican build --formats test --langs en-US ...followed by this command if the test is successful: publican build --formats html,pdf --langs en-US Output will be found in the /tmp subdirectory. ---------------------------------- LOCALIZATION ---------------------------------- Localized versions of the documentation files can be stored in appropriately named subdirectories parallel to en-US. The language code names to use for these directories are listed in Publican documentation, http://jfearn.fedorapeople.org/en-US/Publican/2.7/html/Users_Guide/appe-Users_Guide-Language_codes.html. For example, Japanese XML files would be stored in the docs/ja-JP directory. ---------------------------------- CONTRIBUTING ---------------------------------- Contributors can create new section, chapter, book, publican.cfg, or localized .xml files at any time. Submit them following the same patch approval procedure that is used for contributing to CloudStack code. More information for contributors is available at https://cwiki.apache.org/confluence/display/CLOUDSTACK/Documentation+Team. Jessica T. CloudStack Tech Pubs
