What should we do about API documentation?

Jacob Farber 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
down IMO.

Jacob

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



-- 
Jacob Farber
University of Toronto - ATRC
Tel: (416) 946-3002
www.fluidproject.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://fluidproject.org/pipermail/fluid-work/attachments/20090116/f4dd6177/attachment.html>


More information about the fluid-work mailing list