(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
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
Open Source Applications Foundation "Dev" mailing list
http://lists.osafoundation.org/mailman/listinfo/dev
