Documentation Guidelines post 1.0

[Michelle D'Souza]

I'd like to add a detail to this proposal. Our components have three  
statuses: Sneak Peak, Preview and Production Ready. I think API  
changes to Sneak Peak components should be completely open and do not  
need to be documented as having changed, changes to Preview components  
should be more restricted but they can still be made and must be  
documented as below. Once a component reaches Production Ready we  
should try not to change existing APIs and if we really have to we  
should try to provide backwards compatibility for the older APIs where  
ever possible. Any additions to Production Ready components should be  
documented as below.

Michelle


On 27-Apr-09, at 9:40 AM, Anastasia Cheetham wrote:

>
> 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
>
> _______________________________________________________
> fluid-work mailing list - fluid-work at fluidproject.org
> To unsubscribe, change settings or access archives,
> see http://fluidproject.org/mailman/listinfo/fluid-work

------------------------------------------------------
Michelle D'Souza
Software Developer, Fluid Project
Adaptive Technology Resource Centre
University of Toronto