[TransWarp] Documentation Plans for PEAK

[Phillip J. Eby]

After talking with Ty and Mark over the last few days, I'm revising our 
documentation plans for PEAK, because the current plan isn't working out 
very well.  Although many people have commented favorably on what I've done 
so far, it isn't progressing as quickly or smoothly as I would like, *and* 
I'm pretty sure it's not about the right things.

It's become clear that we need more kinds of documentation as well as more 
of it.  So the new strategy is going to be to create both a "Developer's 
Guide" and a "Tutorial", in addition to the "Reference".  The Tutorial will 
be re-done as the development of a useful application over time, adding 
more and more sophisticated features as it goes.  The "Reference" will be 
generated from docstrings, as it is now.

Finally, the "Developer's Guide" will be a collection of illustrations and 
commentary on the major use cases for each package, along with much of the 
kind of material that is now in the early tutorial draft.  But the 
organization will be different, downplaying sequential presentation in 
favor of compact, separately usable (and writable!) components.

Ty and I have pretty much agreed that although we want a tutorial document 
in the long run, the audience both here and at our workplace would be 
better served in the short run by documentation with less depth, but 
covering a lot more breadth.  And, by choosing an organization that's 
modular, we'll make it easier for more people to contribute to the 
documentation, and it should be easier to write, too.

At present, I'm thinking we'll organize this by adding files like 
DESIGN_GOALS.txt GUIDE.txt, EXTENDING.txt, and suchlike to each 
package.  This will allow the existing HappyDoc extraction process to 
create HTML versions of the structured text, and incorporate it as part of 
the API reference.

I'd also like, however, to add some use case-driven documentation.  For 
example, a "How to configure caching for Data Managers", or "Implementing 
Cross-Database References and Proxies".  Right now, there isn't any 
convenient way to generate such documentation, so it may just have to be a 
set of text files in a "GUIDE" subdirectory of each package, or something 
of that sort.

Whatever we do initially will probably change a bit as we get it settled 
in.  I'd like to establish templates for each of the various kinds of 
documentation, but until we've written some, we won't know what the 
templates should look like.  So that'll be an iterative process.

Anyway, this is just an update so you guys won't be wondering how many 
years it'll be before the tutorial gets to a chapter with stuff you care 
about.  :)  Sometime soon, I'll be updating the master to-do list to better 
reflect our documentation goals for the 0.5 release, which will be to have 
"requirements and design" briefs for each of the binding, config, naming, 
model, and storage packages, that show enough of an idea of what the 
package is/is for that a motivated person could dig into the API docs and 
accomplish something.

The tutorial will remain essentially as it is for the time being.  But as 
soon as the information currently in the tutorial has been assimilated into 
Developer Guide segments, I'll take down the PDF version to avoid confusion 
as to what documentation is most up-to-date or is going to be updated in 
future.

We're also looking at candidates for a sample application to develop with 
PEAK, that isn't related to our proprietary work and can therefore be 
distributed.  We want something simple, because we can't afford to spend a 
lot of time designing it.  I'm also worried that anything we do that's 
complex enough to be useful, is going to have a lot of Zope 3 overhead 
components to explain, if it's web based, or a lot of GUI components to 
explain if we do a desktop app.

It may be that the best thing would be to show how to put a PEAK object 
layer onto an existing application.  For example, to take some existing 
database-backed web application, and then create a tool to import and 
export from XMI files to allow "hot sync" from offline work with that 
tool.  I don't know.  Maybe we need lots of smaller examples, like a Python 
documentation tool that generates the developer's guide from use case 
files, using the naming system interfaces to traverse the input and create 
the output.

So...  as always, your comments, questions, and feedback are 
welcome.  Also, if you have an app you were going to develop with PEAK 
anyway, I'd be more than happy to give you a little extra help with it if 
we can then turn it into an example application.

Per Roche and Ulrich's previous comments about docs and sample apps, 
though, I realize I've got to get a lot more information out there about 
certain parts of the existing code base before anybody can really write a 
good sample app...  which means I need to start writing developer guide 
articles.  :)

So my immediate documentation deliverables for the next week or two are 
probably going to be the updated TODO, coupled with a use case 
listing/outline for the overall developer's guide.  I may also do some of 
the overview docs for the peak.model package, as I'm about to do some 
refactoring there, mostly to bring it into some degree of alignment with 
the OMG MOF metamodel, but also to make it easier to extend for various 
purposes that I'd like to use it for in PEAK (like creating URL syntax 
specifications from a metamodel).

But I digress, and I've got a lot of things to do before I get to the 
office this morning.  Hope this is a useful updated for everybody, and I'll 
probably post various items for comment as things go forward.