Difference between revisions of "Documentation/4.0/HowTo"

From Slicer Wiki
Jump to: navigation, search
Line 36: Line 36:
  
 
= Overview =
 
= Overview =
 +
 
This document aims at describing the steps required to write Slicer user documentation.
 
This document aims at describing the steps required to write Slicer user documentation.
  
The user documentation could be grouped under two main sections:
+
The user documentation subpages are grouped under two sections: [[Documentation/{{documentation/version}}#Slicer_Application|Slicer Application]] and [[Category:Documentation/{{documentation/version}}/Modules|Modules]].
* Slicer Application
+
 
* Modules
+
 
 +
The {{documentation/version}} documentation framework has been redesigned keeping in mind the following principles:
 +
* Single location for editing documentation (either the wiki or the source code), no duplicative editing.
 +
* Smart use of mediawiki templates to enforce consistency and reduce maintenance work.
 +
 
 +
= Naming conventions =
 +
# The application '''Slicer''' should be referenced with an uppercase '''S'''.
 +
# All documentation should be added as subpages under '''Documentation/X.Y/''' where '''X''' and '''Y''' are respectively the '''major''' and '''minor''' Slicer version.
 +
# '''Documentation/{{documentation/version}}/SlicerApplication''' should be the root of all subpages specific to Slicer application.
 +
# '''Documentation/{{documentation/version}}/Modules''' should be the root of all subpages specific to Slicer modules.
 +
# Module subpage should be named after the '''module name''' used in the associated source repository. Assuming the module is named '''Foo''', the corresponding subpage is expected to be '''Documentation/4.0/Modules/Foo'''
 +
# Collaborator names, logos or URLs should be referenced using the convenient [[Template:Collaborator|'''Collaborator''']] template.
 +
 
 +
= Category =
 +
* All subpages should be categorized. See [https://secure.wikimedia.org/wikipedia/mediawiki/wiki/Help:Categories#Adding_a_page_to_a_category]
  
<!-- Work in progress - Jc - Nov 10 2011 -->
+
= Module subpage =
 +
* Base your work on either this [[Documentation/{{documentation/version}}/Modules/YOURMODULENAME|Template]] or an existing module documentation.
 +
* There is a python helper script for SEM compliant tools that can save a significant amount of transcription time:  Slicer/Scripts/SEMToMediaWiki.py
 +
* For CLI modules, the '''SVNREVISION''' revision number is reported on this [http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Applications/CLI page]. The module description and the information for developers would be automatically extracted from the corresponding XML description.
 +
{{note}} For the moment it's required to update that number at multiple location within the wiki source of a given module documentation page. Soon this will be centralized.
  
The basic approach is to have most of the documentation in the source code and to populate the wiki pages using scripts.
 
*For the end user documentation use this [[Documentation/{{documentation/version}}/Modules/YOURMODULENAME|Template]]
 
  
*All module documentation page should be named according to the following pattern: '''Documentation/4.0/Modules/MODULENAME'''
+
= Miscellaneous =
** There is a python helper script for SEM compliant tools that can save a significant amount of transcription time:  Slicer/Scripts/SEMToMediaWiki.py
+
* High resolution logos are in the [[Logo_Gallery|Logo Gallery]]
*High resolution logos are in the [[Logo_Gallery|Logo Gallery]]
+
* The following [Category:Documentation/4.0/Modules  link] will list all modules belonging to the Documentation/4.0/Modules category.
*Collaborators' name, logo, URL have been centralized into a convenient set of [http://wiki.slicer.org/slicerWiki/index.php/Template:Collaborator templates]
 
*The following [http://wiki.slicer.org/slicerWiki/index.php?title=Category:Documentation/4.0/Modules  link] will list all modules belonging to the Documentation/4.0/Modules category.
 
*For CLI modules, the '''SVNREVISION''' revision number is reported on this [http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Applications/CLI page]. The module description and the information for developers would be automatically extracted from the corresponding XML description. '''Note:''' for the moment it's required to update that number at multiple location within the wiki source of a given module documentation page. Soon this will be centralized.
 

Revision as of 00:47, 12 November 2011

Home < Documentation < 4.0 < HowTo



3D Slicer
3D Slicer 4.0
Description
Research platform for the analysis and visualization of medical images, including image guided therapy.
Free and extensible open source package.
Multi-platform Linux, MacOSX, Windows
Version 4.0
License Contribution and Software License Agreement
v · d · e

Overview

This document aims at describing the steps required to write Slicer user documentation.

The user documentation subpages are grouped under two sections: Slicer Application and.


The 4.0 documentation framework has been redesigned keeping in mind the following principles:

  • Single location for editing documentation (either the wiki or the source code), no duplicative editing.
  • Smart use of mediawiki templates to enforce consistency and reduce maintenance work.

Naming conventions

  1. The application Slicer should be referenced with an uppercase S.
  2. All documentation should be added as subpages under Documentation/X.Y/ where X and Y are respectively the major and minor Slicer version.
  3. Documentation/4.0/SlicerApplication should be the root of all subpages specific to Slicer application.
  4. Documentation/4.0/Modules should be the root of all subpages specific to Slicer modules.
  5. Module subpage should be named after the module name used in the associated source repository. Assuming the module is named Foo, the corresponding subpage is expected to be Documentation/4.0/Modules/Foo
  6. Collaborator names, logos or URLs should be referenced using the convenient Collaborator template.

Category

  • All subpages should be categorized. See [1]

Module subpage

  • Base your work on either this Template or an existing module documentation.
  • There is a python helper script for SEM compliant tools that can save a significant amount of transcription time: Slicer/Scripts/SEMToMediaWiki.py
  • For CLI modules, the SVNREVISION revision number is reported on this page. The module description and the information for developers would be automatically extracted from the corresponding XML description.

Note For the moment it's required to update that number at multiple location within the wiki source of a given module documentation page. Soon this will be centralized.


Miscellaneous

  • High resolution logos are in the Logo Gallery
  • The following [Category:Documentation/4.0/Modules link] will list all modules belonging to the Documentation/4.0/Modules category.