What should we do about API documentation?

Jacob Farber jacob.farber.work at gmail.com
Sat Jan 17 23:55:38 UTC 2009


Just a small correction for Mootools (of course :)

They link to their previous versions through numbered sub-domains (
http://docs111.mootools.net/). Their current version is done through a
numberless subdomain (http://docs.mootools.net/)

Just to clarify :)
On Fri, Jan 16, 2009 at 5:31 PM, Colin Clark <colin.clark at utoronto.ca>wrote:

> 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
>
> _______________________________________________________
> 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/20090117/886c9312/attachment.html>


More information about the fluid-work mailing list