reStructuredText
For the eZ components we are currently writing introductionary tutorials for each component. These tutorials should be a first start in understanding the abilities of each specific component without having to go through the full API documentation.
As good programmers we hate to document and thus the easier we can make the process the better documentation we will get. For our internal documents we use plain text files in SVN, describing guidelines and conventions. Those text files are formatted using reStructuredText , a format used by the Python community. It is a very easy to remember syntax, wiki-like, and it is easy to convert to HTML. We also decided to used the same format for our tutorials because it is such an easy format. With a specific PHP script we generate HTML from the tutorials, and add links to the other documentation that is generated by phpDocumentor from our inline API documentation.
Comments
Did you also check markdown and what where your reasons to choose restructured text?
Basically because some of us were already familiar with it. For example I've been using it to document Xdebug's DBGp protocol (http://xdebug.org/docs-dbgp.php). I had also never heard of markdown before, but their syntax seems to be very similar to the one that reStructuredText uses.
Another important benefit of using reStructuredText is that the documentation file (source) without parsing is also very readable.
Life Line
Specify whether public transport stops have tactile paving
Determine the heights of kerbs at crossings
Specify whether crosswalks have tactile paving
Survey if places still exist
Survey hairdresser's customers
Specify whether kerbs have tactile paving
Determine the heights of kerbs
Specify what can be recycled in recycling containers
Specify type of recycling amenities
Specify path surfaces
Survey if places still exist
Specify whether there are cycleways
Specify whether roads have lane markings
Specify whether roads have sidewalks
Specify whether pedestrian crossings have islands
Specify whether pedestrian crossings have traffic signals
Specify road surfaces
Specify access to playgrounds
Specify whether places take fees to visit
Survey whether opening hours are signed
Specify whether pedestrian crossings have islands
Specify whether pedestrian crossings have traffic signals
Determine whether any glass or just glass bottles can be recycled here
Specify type of recycling amenities
Determine place names
Shortlink
This article has a short URL available: https://drck.me/r-4nt