I’ll be celebrating my fifth year as a Masherite in early July. It’s been a wild ride. In my very second week of work, I was asked to speak at a local meetup on behalf of the company on any topic I wanted relating to APIs. I could have chosen to speak on good RESTful design or how to design the underlying architecture to best support a truly scalable system, but those paled in importance compared to the topic I chose: Developer Documentation.
Five years later, I maintain that poor documentation is still the greatest hindrance to developer success — more so than monolithic legacy architectures, un-typed scripting languages, or byzantine release processes. Poor documentation can’t be fixed with something like microservices, or adopting the Go language, or integrating your code repositories with continuous testing and deployment tools. Documentation is a human problem that can only be solved by human intervention.
When I mention this need for a solid documentation process to many organizations, their first thoughts go to hiring teams of technical writers. While it’s true that a technical writer can make your documentation better organized and easier to read, they are actually the last cog in the flow and should be among your last hires when creating your documentation process. Rather, you should start with the team who truly ought to be in charge of your technical documentation: your developers.
Trust me, I’ve already heard it: “The geeks can’t possibly be allowed to write this stuff, they’re barely human themselves. “I’ll side-step the obviously offensive qualities of this sentiment — which is one that I will bashfully admit I very long ago agreed with — and, instead, point out the obvious fact that the audience for such documentation are these very same “geeks”. No one knows better than they what that documentation should contain and how it should be structured, even if they don’t necessarily have the grammar to describe it.
At a previous company I worked for, all developers exposing any service were expected to write the first pass of that documentation themselves in XML using an internally developed stylesheet. What this documentation often lacked in adherence to Strunk and White, it more than made up for in completeness and structure. When it came to exposing web services, our developers were subject matter experts that no army of technical writers could replace.
For the engineers out there having flashbacks to time “wasted” in creative writing courses, I have a warning: learn to be a better communicator, or find yourself toiling away at the same position with no advancement or — worse — on the unemployment line. You may be a master coder, able to optimize flows and bend bits to your whim, but, if you can’t communicate your knowledge to others, you’re little more than a roadblock to progress. The best technical minds are those that can not only share what they know in a way that others can easily understand but are also able to listen to others and synergize those ideas with their own to create new ways of thinking and working. The humble comments that you have hopefully sprinkled throughout your code are the basic building blocks to a wider understanding. The code itself can be communication, but it’s insufficient on its own, mired down as it is by too much boilerplate and the limitations of linguistic syntax.
The bottom line is that your development team must adopt the mindset that they alone are responsible for the accuracy and timeliness of the documentation that describes their code. The buck should not be passed down the line further from the subject matter experts. Subsequent editors may take the raw initial writings and wring them into something more readable, but even that should be confirmed by the developer to adequately convey what their work does and to ensure nothing is missing.
In an upcoming post, I’ll describe a simple documentation workflow you can adapt to or adopt using open standards (specifically, the Open API Specification) that should easily fit into your existing deployment lifecycle.
Resource Url: https://www.tibco.com/blog/2018/07/06/the-most-fundamental-secret-to-api-success-is-good-documentation/