Documentation Guidelines post 1.0

[Michelle D'Souza]

Yes, this is something we've been talking about for a while now.  
Hopefully we'll have some nifty icons we can stick on the relevant  
pages soon.

Michelle

On 28-Apr-09, at 12:23 PM, Eli Cochran wrote:

> 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
>
>

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