Who “Owns” Documentation?

When you manage a software project, how do you delegate the task of documentation? This is something I’ve been thinking about for a while. Many projects deal with documentation at an ad-hoc basis. The implementation developer is usually the one told to document what they’ve done. But generally this is the worst person to call on for the task, for many reasons. The real “owner” of documentation work should be the API architect, but maintaining documentation can easily become a near-full-time job for large projects, and some technical writing skills are required that not all API architects have. In an ideal project, I would propose having a dedicated architect who is also a technical writer. They would handle the maintenance of the documentation but also be kept in the loop on architecture decisions (though they should not be the lead architect).

Why is the implementation developer a bad choice?

I mentioned there are a number of reasons. Let’s go through some of them:

1. The developer knows exactly what the code does — This makes him a bad choice to author documentation, because his perspective is heavily biased. It is easy for this person to miss points of confusion that someone who is less familiar with the codebase may have upon reading the API documentation.
2. Developers are often not skilled technical writers — Technical writing, or writing in general, is a separate skill that not all programmers have. To get quality documentation you should have someone with the right skill set.
3. The developer doesn’t see the big picture — Usually your API’s implementation will bleed into other APIs or depend on domain knowledge from other parts of your architecture (your foo method takes a Bar widget from some external service). The architect is usually the one who knows when this information is new to the reader or if this has already been covered in another document.

In addition to those points, there’s also a small matter of writing style. Documentation can become hard to follow if multiple writing styles are interchanged arbitrarily through documents. Having multiple developers can lead to style inconsistencies, especially if the developers aren’t that skilled at technical writing. Only a small group of people should be managing and maintaining the documentation, to ensure the phrasing is consistent throughout the API.

Why should it be an API architect?

The architects are the ones who have the least bias when it comes to the functionality of the system. A dedicated technical writer may be proficient at writing but may not have an understanding of the entire system and would suffer from some of the drawbacks that developers do (no “big picture”). Also, since an architect’s main responsibility is to define the API, they’re already done half the work of documentation anyway. They might as well go the extra mile and write it down.