What should we do about API documentation?

[Colin Clark]

Hi everyone,

Anastasia and I have been chatting about a couple of points this  
afternoon that I'd like to bring back to this thread.

Infusion is in a bit of a transition period at the moment. We've been  
operating with an "0.x" mentality for awhile now, where the rate of  
change in both our components and framework has been necessarily high.  
We've made a lot of API changes and have introduced substantial new  
functionality in each of our releases. As we approach 1.0, we're  
slowing the rate of change and providing a manageable transition for  
our users from deprecated APIs to the latest and greatest.

We've done a really good job of carefully versioning our documentation  
to help our users contend with the rate of change, and I think it  
helps to support our agility as a community. Perhaps as we shift into  
support a post-1.0 product, we'll find that dealing with documentation  
versioning may get easier, or may require a different strategy  
altogether.

One of my favourite aspects of having our documentation in the wiki is  
that it invites easy contribution. Anyone who has a wiki account can  
make changes. On the other hand, Confluence doesn't seem to provide us  
with sufficient tools for juggling multiple versions of the  
documentation. A pure HTML documentation site, like the idea Anastasia  
suggested, would certainly ease our versioning issues, but it might  
also raise the barrier to entry.

I was curious to see how other JavaScript toolkits handle their  
documentation. Here's a summary:

jQuery maintains their documentation in a wiki. They don't provide  
archives to older version of the documentation.

Dojo appears to have just moved to a wiki for their documentation, and  
similarly doesn't provide old documentation.

Prototype provides a downloadable PDF snapshot of their documentation  
site for older versions of the toolkit.

MooTools doesn't provide older version of their documentation, or any  
real indication of changes across versions within the documentation.

Here are, I think, our goals for Infusion's documentation:

* Easy to maintain and update
* Current and up to date
* Support users who don't adopt the latest release right away
* Foster contribution to the documentation

I'm still not quite sure what the best documentation approach is, and  
I'll certainly defer to Anastasia and the others who are more expert  
in these issues, but let's keep these goals in mind as we come to a  
decision.

Colin

On 16-Jan-09, at 2:25 PM, Anastasia Cheetham wrote:

>
> On 16-Jan-09, at 12:19 PM, Michelle D'Souza wrote:
>
>> 5. Move to another strategy altogether for creating and versioning  
>> API docs. Suggestions?
>
>
> I actually think we're reaching a point where we need a new approach.
>
> My suggestion:
>
> Straight HTML+CSS, in SVN.
>
> Benefits:
> Built-in versioning; versioned docs can be bundled with a release;  
> versioned docs can be easily served up on a public site; much  
> greater control over the appearance of the docs (through CSS).
>
> Issues:
> Slightly more cumbersome edit/share process than the wiki: HTML mark- 
> up instead of wiki, SVN commit/update cycle necessary for sharing  
> changes with others.
>
> I think the benefits outweigh the issues. The initial effort of  
> "porting" what we have over to HTML will be a bit of a chore, but I  
> think it will be worth it.
>
> What do other people think?
>
> -- 
> Anastasia Cheetham                   a.cheetham at utoronto.ca
> Software Designer, Fluid Project    http://fluidproject.org
> 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

---
Colin Clark
Technical Lead, Fluid Project
Adaptive Technology Resource Centre, University of Toronto
http://fluidproject.org