Call to Action - Help Document the Recess Framework

Kris Jordan

unread,

May 13, 2009, 6:18:50 PM5/13/09

to recess-f...@googlegroups.com

Documentation has been one of the sorest spots for new users of Recess. Until now it hasn't been possible for the community to contribute to documentation.

Recess could really use your help with documentation.

Over the last couple of days a big push was made to pull together the existing documentation into the DocBook XML format [http://www.docbook.org/]. DocBook is a common format for technical books and documentation. It is plain-old-XML, is easily modified and contributed to, and has great support for generating down to XHTML, PDF and other formats.

Examples of published output with existing content can be found here:

XHTML: http://www.recessframework.org/book/html/index.html

All-in-One XHTML: http://www.recessframework.org/book/html/the-book-of-recess.html

PDF: http://www.recessframework.org/book/pdf/the-book-of-recess.pdf

How to Contribute to Recess Documentation

Using GitHub and XML documents we can now iterate on the Recess documentation together.

The docbook source can be found on github here: http://github.com/recess/the-book-of-recess

First, fork the repository on GitHub. A forking guide for GitHub can be found here: http://github.com/guides/fork-a-project-and-submit-your-modifications

Second, run the ./scripts/install.sh script from the base directory of the repository. This downloads/unpacks the Java libraries for processing DocBook to generate HTML and PDF with syntax highlighting.

- *nix folks this should just work

- Windows folks use MinGW [http://code.google.com/p/msysgit/] and make sure you have the 'unzip' command available at the command line. If you do not, download the 'unzip' executables from here [http://sourceforge.net/project/showfiles.php?group_id=204414] and drop the executables in your mingw bin folder.

Third, run the ./scripts/publish.sh script from the base directory of the repository. The result should be a folder called 'pub' that has the HTML and PDF output.

Finally, edit the book's content. Don't feel constrained to the structure that's currently in-place. Use the existing chapters for examples of how to mark-up code examples, sections of a chapter, etc. This page is also a great resource on Docbook's tags: [http://www.docbook.org/tdg5/en/html/docbook.html]

Anywhere you can contribute, add comments on, provide a source code example for, please do! While the amount of documentation exists is sparse we should err on the side of quantity over quality. With editing we can refine the rough bits and iterate together towards having the best documentation of any PHP framework.

Finally, request a pull and your contributions will be merged into the documentation.

If you have any questions or run into problems with the install/publish scripts respond to this e-mail thread.

Thanks!