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 [email protected]
Software Designer, Fluid Project http://fluidproject.org
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
---
Colin Clark
Technical Lead, Fluid Project
Adaptive Technology Resource Centre, University of Toronto
http://fluidproject.org
_______________________________________________________
fluid-work mailing list - [email protected]
To unsubscribe, change settings or access archives,
see http://fluidproject.org/mailman/listinfo/fluid-work
