Versioning the technical documentation
a.cheetham at utoronto.ca
Tue Sep 30 19:55:58 UTC 2008
I'm soliciting feedback and suggestions for improvements to how we
version the Fluid technical documentation, which includes the API
pages and the Tutorials.
The current versioning process involves making a copy of each page and
renaming it to add the version code. For example, the page "Reorderer
API" would be copied to a page called "Reorderer API - v0.5" Any links
inside the versioned pages to other versioned pages also need to be
* the increasing amount of technical documentation,
* the highly interlinked nature of a wiki, and
* the use of excerpts,
this process is becoming increasingly tedious, time consuming and
error-prone. I'm looking for a better solution.
One option is to revert to how we did it for the first release: a PDF
While creating the PDF document was also tedious, I think that if the
wiki was appropriately structured (i.e. with respect to page
hierarchies), it would certainly be *less* tedious and error prone.
Another option would be to *not* version the documentation.
This idea is not without precedent. When I look at the jQuery docs (http://docs.jquery.com/
) or the YUI docs (http://developer.yahoo.com/yui/docs/), I can't see
any access to documentation for releases earlier than the current
release. Now, to do this, we would need to maintain the wiki pages
unchanged between releases and keep track of any API changes
elsewhere, and then only update the docs at release time.
I'm interested to know what people think of these suggestions, and
hear what other suggestions you might have.
Anastasia Cheetham a.cheetham at utoronto.ca
Software Designer, Fluid Project http://fluidproject.org
Adaptive Technology Resource Centre / University of Toronto
More information about the fluid-work