On some of our mailing lists, there's been a thread covering documentation recently. The general feeling is that we don't have sufficient documentation for the system, and I'll highlight a comment from the thread that illustrates that feeling, and a disconnect that I think we have. Mind you, I am not trying to "make an example" of anyone who commented in that thread! I'm attempting to use an example to iterate toward a solution:

To give few examples of topics, which all could benefit from answers to questions like: how it hangs together, what was the purpose of introduction (some people my consider that obvious and some may wish to debate), design assumptions about usage, etc.
Multi-process UI - so there is no need to keep directing people at #uiEventFor: and family.

Now as it happens, the multi-process UI (which was introduced in VW 7.1) is fairly well documented - here's a passage from the GUI Developers Guide (one of the PDFs we ship in the "doc" directory):

Prior to 7.1, each window stored a queue of events sent to it, and processing of events was directed by a single instance of ControlManager, named ScheduledControllers. Accordingly, there was only a single UI process, the one run by ScheduledControllers. To allow for multiple UI processes, this mechanism was changed in 7.1.

Each window now has a WindowManager that holds an event queue, representing a single UI process. Each WindowManager can manage the events for one or more windows. Usually, only closely related windows, such as windows in master/slave relation, or windows and dialogs they raise, share a manager. Note that a dialog blocks only the those windows sharing its window manager.

This starts on page 63, and it goes on to talk about using #uiEventFor (etc). So in this case, the issue isn't that it's not documented - it's that a PDF document, separate from the tools that developers live in (browsers, inspectors, debuggers) is hard to use.

The problem is that our PDFs are adaptations of the old printed manuals. Now, printed manuals are good things (albeit expensive), and the PDFs are decent analogs for the printed manuals. However, they aren't a good companion to the Smalltalk system in the "tools I use every day" sense of things. This isn't to say that they ought to be eliminated; rather, augmentation and integration would be highly useful.

Along those lines, I've been thinking about what we could do. Within the system, our Packages and classes are heavily commented, and most of the "API" methods (while not necessarily marked as APIs) are commented as well. What if that were extractable into an easily searchable reference format? What if that reference format were linked to relevant passages in our PDF documentation? In other words, what if you could actually get at the documentation directly from the tools you already use?

I'd love to have feedback on this - either comment directly, or send email to jrobertson@cincom.com

Technorati Tags: smalltalk