What should we do about API documentation?

[Anastasia Cheetham]

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