What should we do about API documentation?

Michelle D'Souza michelle.dsouza at utoronto.ca
Fri Jan 16 17:19:42 UTC 2009

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

More information about the fluid-work mailing list