Documentation Guidelines post 1.0

[Eli Cochran]

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

. . . . . . . . . . .  .  .   .    .      .         .              .                     .

Eli Cochran
user interaction developer
ETS, UC Berkeley