We’ve worked on a number of API documentation projects over the years and regardless of the programming language, technology or purpose, their documentation simply could not have been written by someone without a programming background. The most valuable API technical writers are the ones who can write content from scratch while removing the burden and workload of documentation from the developers. To fill these shoes it takes someone with programming experience, and it always becomes apparent in the writing when the author lacks this background. Here then, is a short compilation of how and why a programming background leads to quality content for API documentation.
In general, a technical writer with a programming background (referred to a “programmer writer” from here on in) will be able to decide what information is correct, infer information and recognize patterns with little or no distraction to the developers. For example, if an API has a common ID value used across a set of functions, but goes by different names in each function, a writer with programming background will instantly recognize that the ID is likely being used for the same purpose across the entire API. A writer without experience in dealing with things like primary keys, unique identifiers etc, may never recognize that the ID is being used to perform operations on a common entity identified by the value of the ID, which may cause their documentation to be confusing or even incorrect.
Another area where a programmer writer excels is in knowing the implicit context and assumptions in which the reader will be applying the documentation to, and can structure the grammar and content accordingly. For example, if an API is a middle layer library which will be called by a client application, then the documentation for each API call does not have to state who will be calling the functions. Ie : instead of writing statements like “Allows the calling application to open a socket for….” or “The purpose of this
On a related note, we’ve found too that many non-programmer writers are too focused on grammar and spelling and this may be another reason why they often write overly long statements as mentioned above. While correct spelling and grammar are certainly important in all technical writing, developers care more about having all of the information required to use the functions including boundary cases, side effects and dependencies on other functions or subsystems. Since a programmer writer thinks like a programmer, they will focus primarily on collecting this information and ensuring that the reader knows everything required to successfully use that function.
Programmer writers also offer one other huge advantage: they are able to identify and filter out implementation details. Often times during development, technical writers will work with raw materials such as design notes, diagrams or even the source code itself. When it comes to these materials, a programming background is essential in order to filter out what readers will need to know and what they shouldn’t care about. In some cases the items to filter out can be obvious such as publicly available functions or constants which should only be called internally (though this is probably a bad API design). In other cases it may be less obvious, such as how much information should be published about a function’s algorithm. Then again, if the algorithm is having some effect on the state of the hardware for example, then this should probably be identified and documented. Either way this is where a programmer writer can make decisions and can even provide beneficial feedback to the development team to help improve the API design.
Similar to this, a programmer writer also has the ability to track down information. In fact we call this “triangulating” information. Often times developers only have a limited view of the system, since they may only work on one part of it and therefore may not be able to provide the writer with the full picture. In fact their understanding of the bigger picture may even be incorrect. A good programmer writer will utilize redundancy where possible, often asking the same questions of different developers in order to piece together how a system works. By taking information from one developer they can use that to formulate more detailed questions for other developers and ultimately develop a clearer understanding of the system as a whole.
One area where many API docs fall short regardless of who they have been written by, is in the introductory and overview material. Microsoft’s “COM” technology was a prime example of this. Its introductory documentation always assumed that the reader knew what problem the technology was solving and thus went straight into complex details on how it solved it. In fact it wasn’t until the introduction of .NET many years later, that I learned what reflection was and realized that this is what COM was trying to accomplish, albeit in a more primitive and complicated manner. Up until that point, I could never really understand why you would want to query an interface, after all, if you’re using a library don’t you already know what interfaces and functionality that library offers?! Had the COM documentation introduced reflection up front and explained what it was trying to accomplish, I might have actually been able to understand and use the technology at the time. The lesson here is then is to generate great introductory material which introduces what problem is being solved, and then get into how the API solves it. Despite the top down nature of this content, we’ve ironically found it best to generate it from bottom up. In other words, we’ve found that only once the entire API has been documented, can we truly say we “know” the whole API and what it does and only then can we write effective introductory/overview materials.
As the old saying goes, “it takes one to know one”, so, the next time you need API documentation, remember that it takes more than writing to generate such technical content.