Katie Capps Parlante wrote:
(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
It would be handy to add to this list of types, limitations on what kind
of types can go in compound types that you wouldn't expect if you were a
python programmer, e.g. ref collections can only have references. Lists
that contain literals can't contain bidirectional refs. How
bidirectional refs differ from single refs, etc.
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
I think it was Bryan who proposed that we come up with a epydoc syntax
to document attributes. This would be really handy for Blocks/Events
since so much of how you use them is by setting their attributes.
* 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
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
Open Source Applications Foundation "Dev" mailing list
http://lists.osafoundation.org/mailman/listinfo/dev
