One of the first tings you should consider when establishing a new project is where the different kinds of project information should go considering the project tools available.

Here is a possible information model based on the SBForge tools.

Wiki

All project information should go here, unless specifically mentioned in the other medias below.

Forces to consider

Pros
  • Easy to write information
  • No predefined model meaning you can structure your wiki documentation as you like
  • History on all changes
  • Lot's of information composition through macros.
Cons:
  • Loosely coupled to source code: This means application related information should be maintained in tools more closely bound to the source code. Examples of such tool are Javadoc, Maven site, Fisheye.
  • No version control: The wiki documentation is not directly versioned as part of the normal SCM work.
  • No model: As a wiki (normally) has no understanding of relations between different kinds of documentation, all links between information elements needs to be maintained manually. A example of information which is difficult to efficiently maintain in a wiki is issue/task related information, because of the rich data model underlying a issue model. Here a real issue tracker should be used, like JIRA.

JIRA

Information regarding thing to do, things being done and things which has been done. This would be tasks,

Maven site

Java doc

  • No labels