Sf Active Documentation

Current State

• The Developpers documentation works and is pretty much up to date.
• The end-user/sysad documentation is completely out of date.

Developpers Documentation

• http://sfa.indymedia.org/docs/tech/cvs/
• We use php documentor for this. basically you just add the documentation in the code. it's pretty easy. there's a script on Stray to regenerate the documentation twice a day.
• In order to try to get it consistent, here's what i do most of the time:
  • documentate the class/page.
  • define all properties & document them
  • document each method adding:
    • @param
    • @return if the method returns something
    • @static if it's a static method
    • @private (eventually, atm we do parse-private anyway)
    • try to use {@link if a method calls other methods.
  • if there's a get/set_property() method, do something like: sets {@link $property}, this makes your documentation easier to document.

'Normal Documentation'

Sections

I think we should split the non-developpers documentation into the following parts:

• end users. (people surfing the site)
• editors (people with an admin account)
• sysadmin people (how to install & maintain, how to upgrade, ....

Format

• We should move away from using html directly, it limits us a lot).
• If we use a format like docbook or so, we can basically use the various scripts to convert the documentation. (create pdf's, ...).

Todo

• Make a GOOD table of contents
  • Each section should have a release number specific page ?
• Each language stands alone. but is translated from english. (otherwise it gets chaos again soon).
• Once the main structure is ready, we should force developpers to update the documentation when they add code.

-- PseudoPunk - 05 Feb 2005
to top