What if I told you that writing software documentation and writing software are the same? It's just that software executes and documentation doesn’t!
Okay, maybe that's a bit of a generalization, but bear with me. If you are a software developer, unless you write code in binary like 100001110010110, what you are writing is words (and, to be fair, more than a few curly brackets and semi-colons) intended for other humans to read. That last part is important, and it's why we don't write code in binary.
Good software is logical, consistent, easy to read, well structured, and follows good design principles. Exactly the same is true of good documentation.
And what makes a good software developer? According to an article by Henrik Warne, a veteran developer, there are five attributes, all of which can be applied both to software and documentation:
1. Problem decomposition
Breaking problems down into smaller, solvable parts
A good developer can analyze problems and de-compose them into their component parts.
A Technical Writer needs to do the same. A piece of writing tells a story, and that story should have a beginning, middle and end. A set of API documentation might be composed of a how-to Guide component and a dictionary-like Reference component. The former walks the user through the process of how to use the API, while the latter provides a way to quickly look up the details of a particular operation or endpoint.
Two weeks after starting as a Technical Writer for APIs & Integrations at Mews back in October of 2021, I sketched the diagram below. It shows an overview of our documentation as I saw it, decomposed into its conceptual parts, with my personal notes on areas that might need attention. The overview is just as relevant now, after twelve months.
Two-week rule: This above example follows what I call the “two-week rule.” I noticed after working for a few different companies that in each case it took two weeks to get to the essence of the problem that needed solving and to define it succinctly. After more than two weeks you are too immersed in the details and it becomes much harder to "see the forest for the trees.
2. Scenario analysis
Considering all different pathways and scenarios
A good developer is also able to see a problem from multiple points of view and consider all scenarios. For every use case, there is a multitude of alternate use cases, alternate paths that the user can go down when not everything goes according to plan.
When I’m working on API documentation, I sometimes think in terms of a reader navigating the documentation, and the paths they will go down. Of course, people are non-linear and rarely take the expected path!
Just like some people will pick up a reference book and flick backwards from the end, and some will confound all expectations and dive straight into the middle, each person reading the documentation will make individual choices, so the documentation content must be designed with this in mind — will it make sense to the reader, regardless of their navigation path?
3. Naming
Naming things so their function is clear
This attribute rightly recognizes the importance of words in software, and the semantic meaning behind them. Let's take a look at a simple example from Mews to illustrate:
GET RESERVATION
As a user of the Mews API, an operation with that name better get me a reservation! That might seem obvious, but it's easy to drift into bad habits and create operations that don't do what they say.
The Mews Spacetime project is a very exciting initiative and a key differentiator for the Mews product family. With respect to naming, this has increased the level of abstraction, from room-night to time-unit, from reservation to service order, from guest to customer.
This is working for us so far, but we have to be careful: go high enough and everything will just be a THING or an ENTITY and will have lost all meaning. Some care is therefore needed to manage this transition for our users. That is one reason why I created the Mews Glossary for Open API Users. With this document, we can unlock the jargon and explain in plain language the meaning behind each piece of terminology and how they all relate to each other, without clogging up the main text.
4. Consistency
Being consistent and applying patterns to manage complexity
This has to be my personal favorite! Consistency is so simple, it brings harmony and order to the world for very little effort. And yet it's a rule that's so often broken.
As a user, I don't want to see GET RESERVATION alongside MAKE BOOKING if reservation and booking are actually the same thing. Likewise, I don't want to see 4th August 2022 in the Changelog of one API, and 8/4/22 in another. These things are easy to fix, and they reduce the cognitive load on the user, as well as making the documentation easier to maintain. I’ve made it a point at Mews to be a stickler for consistency across all our documentation.
5. Learning
Constantly learning and updating
I don't think the software profession is special in this regard, but there's no doubt that we are constantly learning and must be constantly open to new ideas. And not just new technology and new tools, but sometimes new ways of looking at the world.
There are plenty of things to consider in the API space:
- REST vs JSON-RPC
Which is the best architectural style for designing an API?
- OpenAPI 3.0 vs Swagger 2.0
How has the OpenAPI standard evolved and how can we take advantage of its new features?
- GraphQL
A query and manipulation language for APIs, when should this be used?
- Gateways and Portals
An API Gateway is an API management tool which can act as a reverse proxy to accept all API calls for multiple backend services; an API Portal is a place for users to go to access your APIs.
- Postman Collections
An organized collection of pre-built API requests using the popular Postman app.
- Webhooks vs WebSockets
Webhooks and WebSockets are two very different approaches, but both have the potential to provide solutions for pushing event notifications.
Likewise in technical documentation, there are many approaches and many technologies for us to explore, always striving for one main aim — to make the user's experience more remarkable.
Learning can take many different forms, from following blogs, attending webinars and training sessions, and watching conference addresses, to critically examining public documentation. In the technical sphere, installing software and trying out sample code is another common learning tool.
Beyond “Docs as Code”
Five attributes is not the whole story, of course. This is just one particular perspective, but I think it illustrates the point that much of the same approach to software design can be applied to software documentation as well, especially to API documentation.
This goes well beyond the concept of “docs as code”, the principle of applying the same processes and tools used for code writing to technical documentation, something we practice at Mews. In fact, this is a shared mindset.
As Technical Writers, we think about the problem space, the architecture of our content and the way the user navigates that content; we are obsessive about consistency and terminology, and we are always looking to better understand the experience of our users and to explore new ways to delight them. And yes, that's true for software writers as well.
.webp)