What should we do about API documentation?
jacob.farber.work at gmail.com
Fri Jan 16 17:40:32 UTC 2009
Just to chime in on #4, is there no way to export docs from the wiki as
static HTML to post as an online archive somewhere? HTML beats PDF hands
On Fri, Jan 16, 2009 at 12:37 PM, Justin <justin.obara at utoronto.ca> wrote:
> 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:
>> 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:
>> 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
> fluid-work mailing list - fluid-work at fluidproject.org
> To unsubscribe, change settings or access archives,
> see http://fluidproject.org/mailman/listinfo/fluid-work
University of Toronto - ATRC
Tel: (416) 946-3002
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the fluid-work