Having worked in the software industry for oh, forever, I’ve worked with a lot of software developers. And there is a universal truth in the realm of software development: Programmers hate to write documentation. Even those developers who begin a project with the best of intentions end of stumbling somewhere along the way, and the code that is ultimately produced contains little or no useful documentation. But ironically, software developers LOVE good API documentation.
Well, of course they do. Good API documentation leads a programmer by the hand through the jungle of functions, methods, events, parameters and yes, the dreaded best practices. The best API documentation should include the following elements:
- Completeness. Every aspect of an API should be documented.
- Examples. This is very important.
- Sample applications, if available.
- Ease of use and accessibility. API Documentation is best presented in an online format with lots of related links, easily accessible to the busy, impatient programmer.
- Coverage of multiple languages, if applicable and practical.
- Documentation of error codes.
CohenWrite has a lot of experience working with software developers and API documentation. Let us help you help your developers.
CohenWrite is backed by more than 25 years experience writing documentation for software and hardware products using a variety of popular authoring tools. In the “old days,” we used to write long-hand content and hand it over to a typist who prepared printed pages on a Xerox 860 system. Now we use all kinds of sophisticated single-based authoring software to prepare the widest variety of content to software users over the Internet. The tools may have changed, but the fundamental principles underlying documentation content have not. End users still need to know how to get the most of out of your product. This is the value that experienced technical writers add to your product and your company.
Technical documentation includes but is not limited to:
- Step-by-by procedural manuals
- Online help
- Immediate help embedded in the software itself
- Conceptual information
- Visual learning guides
- Collaborative documentation
- Information for programmers (API guides, for example)
- Training guides
And the list goes on.