Blog

Last week a pull request to update the French translation of our user’s guide made me focus my attention on our documentation. I started to think about the requirements for a great w3af documentation: feature complete, easy to write, easy for users to contribute, updated, searchable and easy to find. Our documentation met almost none: the last update was almost a year ago, was written in ODT and manually exported to HTML and PDF and wasn’t indexed by any search engine.

My quest for a better documentation began.

The Open Source community provides developers with great tools such as Git, Python, Django and Sphinx. If you’re not into development most likely you’re not aware of what Sphinx is, but have most likely browsed through the documentation for a project that was generated by it, and hosted at Read the docs.

Readthedocs provides the projects with all of the technical requirements mentioned before, most notably:

• The documentation is written in RST which is then automagically rendered to HTML, PDF and ePub
• The RST format is easy to learn, the files live in your source code repository and a new document version is built each time you push a change.
• Readthedocs hosts the documentation for you at any CNAME
• The documentation is indexed by search engines
• Readthedocs provides you with a simple search engine for your documentation

All these features, and also the fact that there is no lock-in to a specific technology (we could build the Sphinx RST docs and host the documentation ourselves if we wanted to) made the decision a no-brainer: We had to move our documentation to readthedocs.org .

Seven hours of work and many RST tutorials later the work is done and you can read w3af’s documentation at readthedocs.

 

If you’re thinking about doing a similar migration don’t be afraid of how much time it took me, most of the time was spent on re-writing the documentation to make it more accurate and update it to our new framework features.

Since RST is a text-based format and readthedocs provides you with a link to the source of each page, it is trivial for you to contribute to our documentation by modifying the file and sending a pull request. Be the first one to improve our docs and earn the opportunity to decide which feature from our repository gets implemented first!