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