[Dev] Re: Using the description string to document attributes

[Katie Capps Parlante]

(Replying to dev because I think it is of general interest)

Hi Donn,

An idea emerged at the PyCon sprint that it would be really useful to 
have a brief "cheat sheet" of both repository types and blocks/events.

Ted has done a pass at the schema types (after our 0.6 schema api work 
it makes more sense to document types to be used with the schema api):
http://chandler.osafoundation.org/docs/0.6/schema-types.html

I think we were imagining something similar for a list of blocks/events 
that might be of interest to someone experimenting with writing parcels.

So perhaps there are two questions here:
* Is it a good idea to update description strings on blocks and events 
that might appear in a parcel, with a convention of using 
"Required"/"Recommended"/"Optional" at the beginning of the string?

+1 sounds reasonable to me

* Can we use the repository viewer instead of a separate cheat sheet doc 
that will be out of sync if we don't update it?

I'm interested in other opinions about this one.

Cheers,
Katie


Donn Denman wrote:
> Katie and Morgen,
> 
> I'm tasked with documenting Blocks and Events for parcel writers, and  
> it seems to me that leveraging off of your web-repository-viewer  would 
> be a huge help.  It's got all the information, just no  guidance!  One 
> of the things missing is description strings on almost  all the CPIA 
> attributes saying what they do!  The other piece, which  I find to be 
> critical, is a "required from user" bit, that basically  says "you, the 
> parcel writer, should supply a setting for this  attribute".   I don't 
> want to add a bit to any schema for this  (especially now), but I was 
> thinking we could just have a convention  in the documentation 
> attribute, to start it with "Required" or  "Optional", but I'm not 100% 
> happy with this.  There's no way to  quickly and easily tell which 
> attributes are used internally by the  system, and are rarely 
> user-supplied, and which ones are critical  user-supplied settings.  I 
> can write a guide that answers these  questions, but it will get out of 
> date over time -- the information  really belongs on the attributes, in 
> my opinion.
> 
> So I propose that I update the description strings an most things  that 
> might appear in a parcel, and use the convention that the string  will 
> start with:
> "Required" for things you always need to supply
> "Recommended" for things you usually need to supply
> "Optional" for things you sometimes supply
> Anything else means it's either an internal thing or an inverse or  
> something you don't really need to understand.
> Then I'll leverage off of this in my write-up.
> 
> Reactions?
> 
> - Donn