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 [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
------------------------------------------------------
Michelle D'Souza
Software Developer, Fluid Project
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
