Versioning the technical documentation

[Anastasia Cheetham]

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  
updated.

Because of
  * 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  
document.

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