Register (free!) to see more.
What is OpenID?
1. Divide the documentation into two areas — reference and use cases.
2. Take what you have from the developers, which is reference, and organize it by interface. Maybe move any long examples and use-cases to the use case section. Although it's useful to have examples online so programmers can cut and paste them.
3. Design use case documentation that is completely separate from reference information.
4. Try to determine how "open ended" the application programming interface (API) is intended to be. Can the programmers use them to do quite widely divergent things, or are the APIs quite narrow in their scope?
5. See how much of the API reference information (about properties, methods, events) can be automatically generated.
Make a list and get to know all the methods and interfaces:
- Identify methods that simply return, methods that don't have arguments, etc.
- Identify methods that are callbacks.
- Identify methods that are variations of each other. Maybe one method takes a short while another takes a string, or maybe they vary in their return type.
- Identify methods that return a handle to another object in the API.
- Separate interfaces that are intended to be used "as is" from interfaces that are intended for you to implement.
6. Group methods by how they relate to each other in telling a story. (This is where you'll spend lots of time interviewing the developers.) Perhaps one method is consistently called after another method. Maybe draw rough flowcharts. There may be some methods that can't be grouped with others - that's not necessarily an error - they just go in the "miscellaneous" category. Your stories may end up very precise or very sketchy, depending on that how you answered the above.
7. Figure out whether the method is one that the programmer is probably looking for (as in "I know there has to be a method that does X") or one that they wouldn't think to look for if you didn't tell them. This may help in figuring out how much needs to be said about a method.
8. Write up use cases based on these groupings. Make sure you have mentioned each method at least once. How much you talk about each method can vary from just a mention (to simply point the programmer to the existence of the method) or lots of description of the ins and outs. You can divide use cases into chapters or sections based on the package.
9. Put in flow charts or call diagrams or object diagrams if it helps.
10. Leave all the reference information online (and preferably integrated with the software) and put the use case information in both online and printable forms.
Note: Those of us in the over-40 crowd (ahem) liked the idea of a paper manual, to save out poor old eyes.
This is another way of looking at the difference between the reference and use-case stuff — you might want to be able to sit down with a coffee and read all about the use cases (either online or from a paper manual), while it is more likely you will want to just "look up" the reference information as you are writing code.
If you do decide on a printable manual: doing indexes is generally a pain and usually unfeasible given time constraints with tons of work to create and maintain, so a good compromise is to include a "Which method where" towards the beginning of each chapter. Make a table of method names (sorted alphabetically) and provide a one-line explanation and a cross-reference to the page that discusses it.
Contributed by Catherine Buck, Senior Tech Writer
This article originally posted in an email on nettechwriters.
Disclaimers: This description may contain platform-specific terminology, but you get the idea. This is one professional's methodology. If you can create a more complete set of docs another way, go for it.
