What should we do about API documentation?
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
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
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
Software Developer, Fluid Project
Adaptive Technology Resource Centre
University of Toronto
More information about the fluid-work