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