What should we do about API documentation?

[Justin]

Just to way in again.

My first choice would be option 3 and my second choice would be option  
2.

The problem with option 1 is that, I feel, we need to provide the user  
with documentation for the version that they are using.

The problem with option 4 is that we may end up with a set of large  
documentation files. Also with a web version you could probably throw  
in live examples on to the documentation page. I don't know if we do  
this  yet, but at least it would be a possibility.

- Justin
On 16-Jan-09, at 12:19 PM, Michelle D'Souza wrote:

> 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
>
>
>
> _______________________________________________________
> fluid-work mailing list - fluid-work at fluidproject.org
> To unsubscribe, change settings or access archives,
> see http://fluidproject.org/mailman/listinfo/fluid-work