Forum OpenACS Q&A: Response to Code freeze in favor of documentation for 4.7

Much as I like documentation, I'm not sure what the right solution is. I'm afraid of documentation that gets out of date, or documentation that goes unused, and thus becomes overhead. So I'd like to have a discussion about the kinds of documentation that we need. It's not something I've thought a lot about, so I'm sure that there are others out there with more qualified opinions, but here are some loose ideas to start with:

PACKAGE DEVELOPER'S GUIDE

- We need a package developer's guide and tutorial for how to build "good" OpenACS packages.

It should cover things like

- how to use ad_form,

- how to design your data model

- when and how to use content repository,

- how to internationalize it,

- how to write proper tests,

- how to write your requirements and design doucments and the end-user documentation,

- coding style,

- API design,

- other standard services like workflow, notifications, attachments, etc.: When to use them and how,

- UI guidelines,

- etc.

This is critical, because it's prescriptive, so it'll improve the quality of all new packages being built, and at the same time make it easier for new people to get started on building applications for us. And it must get updated to contain the latest knowledge about best-practices. Therefore we need a maintainer of this document, who can get support from others, of course.

END-USER DOCUMENTATION

This is important. I think it would be a really valuable investment to come up with a simple framework for this, so online help can be invoked in a standard way throughout the toolkit. Perhaps something as simple as adding a "Help" link to the default-master template, and having a directory at package/www/help store the help text files. They should also have a consistent look and style, since they'll become part of the UI.

REQUIREMENTS AND DESIGN DOCUMENTS

These are important for documenting assumptions and design decisions. But they must be kept short and to the point, and let's not try to be too strict on the templates for this, since this seems to encourage people to put lots of irrelevant details in there. It can also be really hard to write your assumptions clearly, since they're frequently assumptions you've made without realizing. I like Joel's approach to specifications: http://www.joelonsoftware.com/articles/fog0000000036.html

DEVELOPER DOCUMENTATION

Service packages or subsystems like CR, notifications, workflow, form builder/ad_form, etc., need a document explaining how to use them. These also need to be kept short and to the point, and shouldn't deal with the details of the APIs.

Other developer documentation, like API documentation and such, should be kept in the code.

-

Hm, this list got long after all. I'm not too happy with saying "if you can't write documentation, you can't contribute". I think there is going to be an eternal problem, because it is intrinsic to the people and the process.

Perhaps we can change the attitude. I think there's a good chance that if we improve the documentation to a point where it's actually useful, then the more people start using it, the more people want to contribute to it. But we should refrain from setting expectations that are so high that they're not going to be met, anyway.

Hm. These were loose thoughts. I hope they were useful to some.

/Lars