##Guidelines = 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|structure]] * [[#Graphics|Graphics]] should be drawn in [[http://live.gnome.org/Dia|Dia]] * [[#Stand-Alone|Stand-Alone Documents]] should be placed in SVN * Wiki pages are collected into books via the [[MoinMoinBook| moinmoinbook script]] * Use the available [[http://merkur/domswiki/?action=fullsearch&value=Template|templates]] for [[#Specific|specific documents]] * Information should not be replicated, neither within the new DOMS wiki or between the [[#Old|old DOMS wiki]] and the new * The documentation [[#Language|language]] is English * And please share your [[#Hints|hints]] <> == Structure == All pages should fit into the DOMS Wiki Structure Diagram: [[http://merkur.statsbiblioteket.dk/svn/doms/trunk/docs/guidelines/fig/wikistructure.dia]]. {{http://merkur.statsbiblioteket.dk/svn/doms/trunk/docs/guidelines/fig/wikistructure.png}} <> == Graphics == Diagrams cannot be drawn in the wiki. We recommend using [[http://live.gnome.org/Dia|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| moinmoinbook script]]. <> == Guidelines for specific documents == Please use the available [[http://wiki.statsbiblioteket.dk/domswiki/?action=fullsearch&value=Template|templates]]. There are templates for most of the pages in the [[#Structure|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 [[https://addons.mozilla.org/en-US/firefox/browse/type:3|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 [[https://addons.mozilla.org/en-US/firefox/addon/4125|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.