Talk:Documentation Team

One programmer's opinion:

I believe it is a mistake to rely on "read the code" as a solution to sugar documentation. There needs to be a document for each class this organization invents. The document should contain at least the following:

1. What the class is for and when it's appropriate for the developer to use it.

2. What the class is derived from (if anything), what base-class methods/attributes it overrides/extends/hides and what new methods/attributes are provided. *

3. Methods and attributes reference (it could be appropriate for this part to be generated from the code).

(*) Pardon me if that's not Python-speak: I'm new to the Python language. Methods are the things in a class that start with "def"; attributes are the class's data.

Finally, there needs to be both an index to classes and a "roadmap" showing how the classes relate to each other. Examples would be nice to have, too, but this "developers' reference guide" is essential -- otherwise the learning curve is too steep and third-party developers will go devote their time to some easier-understood project.

I hate to hold Microsoft up as a good example (they aren't -- they're only so-so when it comes to documentation), but the hyperlinked documentation for the Microsoft Foundation Class library is fairly decent. The documentation for the Swing library in Java is nearly as good, though the class library reference part could use a better layout.

A nice-to-have in all of this would be the ability to call up the relevent documentation while coding, as can be done in Visual Studio. dave 20:03, 19 May 2008 (UTC)