How-to Help Document the Recess Framework

Posted May 15, 2009 by Kris Jordan | Comments ( 3 ) | Filed in: Community | | | | |

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 leave comments below.

Comments

Comments are moderated. It may take some time for your comment to appear.

Recess can only be as good as the thoughts that go into it. Let us hear yours...

  1. Posted by Maiquel Leonel on May 15, 2009
    Right!
    Congratilations!!
    I would like to help on translation to brazilian portuguese and on development of a i18n plugin!
  2. Posted by Kris Jordan on May 15, 2009
    @Maiquel: Would love to have your help on a translation to Brazilian Portuguese. I will look into setting up DocBook to generate multiple language versions. In the mean time it would be great to have your assistance filling out holes in the existing documentation so that there's enough content to translate!
  3. Posted by Jackson F. de A. Mafra on May 15, 2009
    i'll help maiquel in translations and i18n.We wish to use the recess in our company projects. First we need to integrate with smarty templates, after that, homerun!
    Cya.

You must login to comment on this page.