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'


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, ....


  • 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, ...).


  • 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
Topic revision: r1 - 05 Feb 2005, PseudoPunk
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback