Documentation Guidelines post 1.0

[Anastasia Cheetham]

Now that Infusion 1.0 is out, we have to be a bit more careful about  
updating the documentation on the wiki. Because we're currently not  
creating any form of "snapshot" of the documentation as it applies to  
a release, we should consider the documentation to have multiple  
audiences: 1.0 users, trunk users, and in the future, 1.1 users, 1.2  
users, etc. We have to remember that even after we release 1.1, some  
users will still be using 1.0.

To that end, we need to ensure that our documentation makes it  
perfectly clear when things are different between versions. Here is a  
proposal as to how we can do this (thanks to Michelle for helping me  
flesh these thoughts out) - I encourage suggestions for improvements  
on these ideas:

1) Anything that is new (i.e. introduced post-1.0) should be indicated  
as such, with
      "New in trunk" or "New in 1.1" etc.

2) Anything that is being deprecated or removed should be indicated as  
such, with
      "Deprecated in 1.1" or "Removed in 1.2"

3) Anything that is changed (and these will hopefully be few and far  
between) should be indicated as such, using the following conventions:
   3a) While a change is in trunk, and before it's been cut in a  
release, the "official" docs should show what was in the latest  
release, and include a note as to the change, such as "(Changed to XXX  
in trunk)"
   3b) After a change has been released, the "official" docs should  
show the new version, along with "(Was YYY in 1.0)"

Thoughts?

-- 
Anastasia Cheetham                   a.cheetham at utoronto.ca
Software Designer, Fluid Project    http://fluidproject.org
Adaptive Technology Resource Centre / University of Toronto