Don, Is there a good CR example in the code now? news is small and
and could be made into a good example with some cleanup but I think the permissions stuff in news is a trainwreck. Bboard, wp-slim, file-storage, etc all are a little too large and generally too
ugly to present as examples. News also does use the service
contract stuff for searching which would be a good way to introduce
both of those.
Jun, your document is useful and yes, it would be nice to have everything be consistent. One thing I would say is I would like
to split out just the negative things and make it a "Common Errors"
document and take all the afirmative suggestions and incorporate them
into the developer doc.
Ben, collaboration would be welcome. I have an outline in mind
but had not thought too deeply about specific examples (the
above on news was my first stab at it). I will write out an
outline and you can have a look and see where we go from there
(and anyone else who wants to be involved is welcome as well).
I do recognize you are very busy documenting the APIs you have
already developed and writing proposals so I don't want to make
too large a claim on your time :)
I think there is an awful lot that can go on in parallel and people
should also think about taking a look at the api documentation since
that can (and should) be a much better guide to best practices
if we just take the time to document what we think people should
really be using. The embeded documentation for ad_form,
ad_page_contract, and export_vars are good examples of what we can
achieve on specific important interfaces. Currently about 1/3 of
the functions lack any documentation and about 1/3 have neither
-public or -private designations (which means we can't say "look
at only -public procs"). I would say there are also about 50
procs which should probably be deprecated (although not so many in
the core now).
Sadly I am completely focused on developer documentation and
hopefully someone will step forward on the user side. I also wonder
if we should have a document oriented towards designers and
people who don't need to dig in the code but do need to understand
some aspects of the system (templating mostly but also how to
theme subsites, etc). Skin halfway covers this ground
but is out of date and I think easily overlooked.
