DOMS Documentation and Wiki Site Guidelines

Documentation is primarily written on the wiki site and should follow these guidelines. Points to remember are:

• The page should fit into the wiki site structure

• Graphics should be drawn in Dia

• Stand-Alone Documents should be placed in SVN

• Wiki pages are collected into books via the moinmoinbook script

• Use the available templates for specific documents

• Information should not be replicated, neither within the new DOMS wiki or between the old DOMS wiki and the new

• The documentation language is English

• And please share your hints

Structure

All pages should fit into the DOMS Wiki Structure Diagram: http://merkur.statsbiblioteket.dk/svn/doms/trunk/docs/guidelines/fig/wikistructure.dia.

Graphics

Diagrams cannot be drawn in the wiki. We recommend using Dia as it has nice predefined UML templates and can be exported to a large number of formats including PNG, which can be in-lined in the wiki (don't know how to get the arrows straight though). Remember to include a link to the original. Link to the original using square brackets:

[http://merkur.statsbiblioteket.dk/svn/doms/trunk/docs/guidelines/fig/wikistructure.dia]

and insert the png on the wiki page without square brackets (this image is also included by moinmoinbook):

http://merkur.statsbiblioteket.dk/svn/doms/trunk/docs/guidelines/fig/wikistructure.png

Use the Flowchart sheet for drawing boxes, as it supports lots of connectors and text linked to boxes.

'Stand-Alone' Documents

External diagrams and word processor documents are stored in SVN; see Directory layout. It is recommended to use the wiki rather than producing stand-alone documents. Wiki pages are collected into books via the moinmoinbook script.

Guidelines for specific documents

Please use the available templates. There are templates for most of the pages in the structure diagram.

Iteration Documentation

• Iteration pages are created with the IterationTemplate

• An iteration page links to a number of action pages that describes work to be carried out during the current iteration
• The iteration page includes links to the tasks addressed by each action
• The Iteration page also shows estimated time, responsible developers and the current completion status of each action

Action Documentation

• Action pages are created with the ActionTemplate

• Each Action page contains a detailed description of the work that needs to be done and the goal/result to achieve

Milestone Documentation

• Milestone pages are created with the MilestoneTemplate

• A Milestone page defines which WBS tasks must be completed at a given time in the project

Project Management Documentation

The project management documentation includes project charter, work breakdown structure, time estimates, risk analysis, stakeholder analysis, communication plan and agendas and minutes for project meetings.

Work Breakdown Structure (WBS) Documentation

• The WBS main page lists a number of high-level tasks that must be completed in order to achieve the goals of this project.
• The WBS is organised as a tree, hence, each Task may link to one or more sub-tasks

Task Documentation

• Task pages are created using the TaskTemplate

• A Task page describes non trivial task to carry out and the more complex tasks may also link to one or more sub-tasks, also created using the TaskTemplate

• Any Task page may also link to more elaborate analysis documents, design documents and so on, where appropriate

Analysis Documentation

• Use the AnalysisDocumentationTemplate

• Analysis documents must give a detailed explanation of the problem
• Include assumptions and prerequisites for the task
• May use use-case diagrams etc. where appropriate

Design Documentation

• Use the DesignDocumentationTemplate

• Include detailed explanation of architecture
• Include overview of software/code modules and packages
• Must give a detailed explanation of major design decisions

Documentation of Set-up and System Maintenance

• Use the SystemMaintenanceDocumentationTemplate

• Include overview of architecture
• For each software component
  • Include detailed configuration instructions

Stakeholder Analyses

• Use the StakeholderTemplate

• Include role, interest, success criteria and contact information of the stakeholder

Risk Descriptions

• Use the RiskDescriptionTemplate

• Include description, when to react, reaction and responsible persons

Meeting agendas and minutes

When creating agendas for meetings please use the AgendaTemplate and use the MinutesTemplate for the minutes from the meetings. Please refer to the Minutes and Agendas for instructions about where to place agendas and minutes, as well as correct naming of the pages.

The Old DOMS wiki site

• Information should not be replicated, neither within the new DOMS wiki or between the old DOMS wiki and the new
• Content copied from the old DOMS wiki into the new one should be deleted and replaced with links to it new location

Language

The DOMS wiki language is English. The wiki spell checking does not work at present (no dictionary), however, Firefox users can install a dictionary for the built-in spell checker. Just right-click on the text field, when editing a page, to select language and/or force the spell check to be executed.

Hints

• The It's All Text Firefox Add-on let's you right click on a text area to open the text in your favourite text editor; when you save it, it'll refresh in the web page.