Below are my notes and highlights from this session at Write The Docs Europe 2016 in Prague. This is part of a series I wrote during the conference. This is not meant to be transcriptions and may have missed points made during they talk. They solely reflect my interpretations of the talk.
Using Meaningful Names to Improve API Documentation
Martin P Robillard has summarized how to make APIs and their documentation useful:
- include good examples
- be complete
- support many complex usage scenarios
- be conveniently organized
- include relevant design elements
The Focus is on Being Complete
In the context of this talk, API documentation is confined solely API references.
Jan did his work using an example from the Java 8 Mail API. When writing the API, the default tooling suggests basic templates to be used in comments. These templates are often casually updated and passed through almost unchanged into the comment.
How could we improve the tool/defaults to help improve the experience?
The creation tools all focus on the parameters, exceptions and results. These items form the signature of an API call. However, Jan believes that by using the names associated with these items, it is possible to derive relevant aspects of the API and encourage better work.
He then walked through an example of using an identification process with Volkswagen buses. As we use more of the information, it becomes easier to identify the buses. This led to a three step process for improving APIs:
-
Find a meaningful verbs that describes the operations.
Do this by scanning the API.
-
Find the best matching documentation pattern.
These patterns indicate questions likely to be asked by a developer. For example, if you see the verb, “submit,” it is logical to ask “where is it going?”
-
Match the API documentation against the pattern.
Offer these questions as templates and have the API programmer provide what is appropriate. Essential prompt the programmer to think through the likely needs of the API consumer.
Jan has developed a set of sample patterns and processed the Java 8 Mail API. You can find the work in his GitHub Repository.