This page will discuss documentation pages that need work, imo.
The general principle I would like to advocate is that introductions have 3 main parts that should appear *in order*.
1. A discussion of what the feature is or does, in simplest possible terms.
2. A discussion of how the feature works, again in simplest possible terms.
3. Details.
Let's apply this to the all-important Chapter 7, the services authoring guide.
Here is the start of the documentation:
[quote]
PIDA has a very general concept of services (you might call them plugins in another application). In general, a service is able to define any PIDA function, that is anything PIDA can do, a service can do it too.
PIDA is essentially a bunch of services bound together by a Boss. The services are discovered from service directories and loaded by a Service Manager for the Boss.
7.1. Service Overview
A service is comprised of a directory on the file system. This directory is a Python package with data.
The structure of this directory is like so for a service named "myservice":
[directory structure ommitted]
[End quote]
Does this writing satisfy step 1? That is, it is a discussion of what the feature is or does, in simplest possible terms?
It's a start. I would suggest rewriting the documentation something like this.
Services are self-contained units of python code and other supporting data. Services provide all of pida's capabilities. Indeed, Pida consists entirely of a set of services and a **boss** that loads and manages those services. Users can create new services, and new services can modify the workings of existing services. Thus, users can customize all aspects of pida (except the boss, that is).
It might be good to point out similarities of this architecture with the Eclipse architecture.
Does this writing satisfy step 2? That is, does the documentation tell how the feature works, in the simplest possible terms? Not at all! In fact, step 2 is entirely missing. Instead, the documentation jumps immediately to step 3, implementation details.
What's missing is what services can do. We know, in general, that services can do everything, because almost everything in pida is a service. But that's not exactly a lot of help. Presumably, services provide various kinds of services, hence their name. But it would be good to say that services can do the following:
- define areas on the screen,
- define commands or other executable code,
- define bindings and other settings,
- modify the workings of other services,
- communicate with other services,
- etc.
Presumably there protocols that allow services to do what they do. It would be good to introduce those protocols. Etc.
Only *after* step 2 has been handled should the documentation proceed to step 3, the details. Furthermore, it's not likely that the mundane packaging details of directory structure is the most important part of step 3. Presumably, step 3 would discuss how all the features discussed in step 3 are actually implemented.
As I look at chapter 7 I am overwhelmed with details without ever seeing the big picture. In other words, steps 1 and 2 are almost completely missing.
Maybe the way forward is to look at an actual plugin. How would you describe *what* the plugin does? (step 1) How would you describe *how* the plugin works **without** details. (step 2) That's what the newbie wants to know. Only after step 2 can the newbie understand step 3.
Now I would like to introduce some 'recursion' into my proposed documentation scheme. Consider all the items I mentioned in my discussion of step 2 above:
- define areas on the screen,
- define commands or other executable code,
- define bindings and other settings,
- modify the workings of other services,
- communicate with other services,
- etc.
You could apply the same 3-step plan to each of *these* steps. Let's take the first item, "define areas on the screen". Step 1 would be a discussion of screen areas. What kind of areas can be defined? What can be put in each area? How do different areas interact with each other? Step 2 would be a *general* description of the tools involved, *without* details. Finally, *after* after a full and complete general picture has been presented to the user, the documentation could discuss the gory details.
HTH. These are only my suggestions. Real writing can't be reduced to a formula.
Edward
