What should we do about API documentation?

[Michelle D'Souza]

There have been several threads about API documentation in Fluid  
Infusion over the course of the project. We still haven't come up with  
a sustainable plan. I'm going to try to articulate the options and  
their pros and cons here and hopefully this will lead to a decision.  
I'm leaning toward option 3 for 0.7. This is the strategy that Justin  
laid out a couple of days ago. What do others think?




1. Don't create versioned API docs. This was what we did for Fluid  
Infusion 0.6.

Issue - users will have incorrect documentation if they are using  
anything but trunk
Benefit - no additional work when releasing


2. Clone all the API docs. This was the strategy that was used in 0.5  
see: http://wiki.fluidproject.org/x/-J87

Issue - onerous, time consuming and error prone release time task
Benefit - complete versioned API docs are available for the user


3. Link to specific revisions of a page. See an example here: http://wiki.fluidproject.org/x/FQlS

Issue - links from an old revision to another API document will link  
to the most recent revision and therefore a different version of Fluid  
Infusion API docs. Try clicking on the Simple Text Inline Edit API  
link from the 0.7 Inline Edit API page to see this issue.
Benefits - versioned API docs are available to the user
		- fairly simple release time task


4. Create a pdf of relevant pages. This was the strategy we used in 0.1

Issues - docs are not ideal to use
		- error prone release time task
Benefit - versioned API docs are available to the user


5. Move to another strategy altogether for creating and versioning API  
docs. Suggestions?



------------------------------------------------------
Michelle D'Souza
Software Developer, Fluid Project
Adaptive Technology Resource Centre
University of Toronto