FREMO Interlocking

How to build developer documentation

We decided to write the whole developer documentation in HTML with some extensions in PHP. This allows, to easily extend the documentation using the CVS with all its capabilities as merging, versioning...

This is my suggestion, how to manage the process of building up the developer documentation. [BA]

Everybody, who wants to contribute to the developer documentation, will get his own "class" in the .css. So, his comment can be easily recognized. This is an example with my .css-class [BA]

The process for building the docs:

  • First step: If the topic exists, you will add your ideas or proposal as a comment with your .css-class.
    If the topic is new, you will have to do some more work. You will have to add a page or a complete directory with dozens of chapters, sub chapters and so on, as appropriate. Please use the same structure as the site started. If you think, we need changes to this, we should discuss it separately.
  • Second step: Everybody can put his comments, with his own class, to the proposal. If necessary a discussion should be done in the appropriate mailing list.
  • Third step: If we get a common sense, the author of the proposal puts all the comments into the document, and we get a new version.

Please keep in mind, that all these steps should be done in CVS *and* the web site. If anybody has a good idea, how to keep both in synchronization, please put a comment in this place..