[Insight-developers] First crack at usage documentation

[Will Schroeder]

Hi Folks-

Several people have contacted me regarding documentation. Stephen Aylward 
sent me an outline describing a comprehensive documentation suite, and 
Sayan Pathak and I talked about more extensive "class/group of classes 
documentation" that he has just sent to the list. Bill Hoffman showed me 
the vxl documentation which is arranged in the form of a book 
(http://www.robots.ox.ac.uk/~vxl/book/) also see 
http://www.esat.kuleuven.ac.be/~targetjr/www.robots.ox.ac.uk/vxl/.

My take from these discussions is that it is time to create an outline for 
documentation, both in terms of the Insight/Documentation directory 
structure, as well for the arrangement of web pages and other material. I 
particularly like the idea of building a logical arrangement of material - 
consistent in style and layout - that we produce as a"book" or "books." 
With that in mind, I'd like to propose a strawman organization for the 
documentation. I expect that this will not be completed until the end of 
the third year, but if we can share the vision of the framework, it will 
expedite the creation of this invaluable resource. (Aside- Kitware has on 
its WA3 and in its proposal the task of organizing/helping create 
documentation and training materials)

What I have in mind currently is to build three "books" - User's Guide, 
Developer's Guide, and Algorithm Guide. I'd like to see
each less than 250  pages (although the algorithm guide may grow larger). 
Issues: I'd also like to settle on a implementation (e.g., Word, etc.) that 
can be used to create both a nice looking text as well as producing html. 
I'd also like to adopt some styles that are reasonable consistent. Suggestions?

Anyway, here's a rough outline. (Some of this material came from Stephen 
Aylward.) Sayan is going to lead the discussion on documentation of Friday, 
maybe we can talk about this then. I'd also like to hear suggestions, 
criticisms, etc.

Will
------------------------


Book 1- The Insight User's Guide (lots of examples - in C++)
Chapter 1 - Introduction
	- What is Insight?
	- Organization
	- Additional Resources
Chapter 2 - System Overview
	- Hybrid Compiled / Interpreted Architecture
	- Generic Programming
	- Data Processing Pipeline
Chapter 3 - Getting Started
	- Overview
	- Get The Software
	- Installation
		a. Windows
		b. Unix
	- Running (Insight HelloWorld)
		a. Windows
		b. Unix
	- Testing
		a. The Quality Dashboard
		b. Running a Test
Chapter 4 - The Basics (lots of examples)
	- Smart Pointers & Reference Counting
	- The Object Factory
	- The Image Class
	- The Mesh Class
	- Creating a Data Processing Pipeline
Chapter 5 - Segmentation
	- Pick several important algorithms and demonstrate them via example.
		a. Class hierarchy
		b. Landmark implementations
		c. FEM implementations
		d. Adding your own
		e. etc.
Chapter 6 - Registration
	- Pick several important algorithms and demonstrate them via example.
		a. Pixel Labeling Class hierarchy
		b. Adaptive Surfaces Class hierarchy
		c. Adding your own
		d. etc.
Chapter 7 - System Interface
	- Image Class
	- Mesh Class
	- Process (Data) Objects
Chapter 8 - Language Bindings
	- Typeless C++
	- Tcl (example)
	- Python (example)
	- Java (example)



Book 2 - The Insight Developer's Guide
Chapter 1 - Introduction
	- Purpose
	- Organization
	- Additional Resources
Chapter 2 - CMake
Chapter 3- Reference Counting and Smart Pointers
Chapter 4- The Object Factory
Chapter 5 - Managing Pipeline Execution
	- The Update Mechanism
	- Streaming Data
Chapter 7 - Wrapping C++
	- Overview
	- XML Notation
	- Typeless C++ Layer
	- Tcl
	- Python
	- Java
Chapter 8 - Extending the Image Class
Chapter 9 - Extending the Mesh Class
Chapter 10 - Writing a Process (Filter) Object
	- Overview
	- Input Image / Output Image
	- Input Mesh / Output Mesh
	- Other
Chapter 11 - Testing the Software
	- The Quality Dashboard
	- Submitting a Dashboard



Book 3 - The Insight Guide To Algorithms
Chapter 1 - Introduction
Chapter 2 - Segmentation
Chapter 3 - Registration
Chapter 4 - Supplemental
	- Transformation classes
	- etc.