I second Michelle's addition. However, if we go this route we should
probably tag each component landing page, the API page and the
Tutorial with the status. We don't want folks to feel to "comfortable"
working with a Sneak Peak component.
It is more than acceptable to expect that Sneak Peak components will
be volatile.
- Eli
On Apr 27, 2009, at 7:38 AM, Michelle D'Souza wrote:
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
. . . . . . . . . . . . . . . . . .
.
Eli Cochran
user interaction developer
ETS, UC Berkeley
_______________________________________________________
fluid-work mailing list - [email protected]
To unsubscribe, change settings or access archives,
see http://fluidproject.org/mailman/listinfo/fluid-work
