Good Technical Content: Procedural Clarity With Conceptual Detail
Both forms of technical writing rely on the writer being able to clearly, and quickly, articulate:
- The intended purpose of the piece
- Its relevance to the intended audience
- A logical information hierarchy
- Accurate and concise–but sufficient–technical detail
Developers are notoriously busy, often dealing with multiple projects and priorities at once. However, this is also a group that prizes skill development and has little fear when it comes to deep-diving into new technological concepts. Documentation that allows them to quickly find an answer, but also allows them to “double click” into the details is documentation that has struck the ideal balance.
In our experience creating technical documentation for software providers and hardware manufacturers, there is a delicate balance to be struck between clarity and comprehensiveness that is best attained through a thorough discovery and audit process. Some of the key considerations to define early on include:
1. Who’s Accessing the Document?
It should be assumed that your primary audience is the software engineers, architects, and developers who will ultimately need to use your technical documentation to use your product or service as intended.
But it’s not just your customers’ developers who need to understand and engage with your documentation: internal audiences are just as vital for ensuring ongoing product iteration, support, and innovation.
This means having a good understanding of not just the roles and responsibilities of all the different stakeholders who will need to use the document. Effective technical documentation would also be graded according to each user group’s technical maturity, and the technical maturity of the organization as a whole.
2. When Will They Access It?
As mentioned when we were defining the differences between conceptual and procedural documentation, different readers will be looking to the documentation to answer different questions at different times.
Information architecture, messaging hierarchies, formatting, and even the indexing system you use to organize information can help or hinder a technology’s successful rollout and adoption.
3. How Does It Fit Into the Product Information Ecosystem?
Every FAQ, community answer, or document page fits into a broader story about the product or service, with upper funnel marketing at the beginning and technical support documentation at the end. Along the way though, gaps can appear in this story, leaving developers without the means to realize a product promise made in the early sales stage.
As part of a comprehensive DaaS offering (Documentation as a Service), a technical writer, or technical writing team, should conduct a thorough audit of available documentation, and zoom in on the features, capabilities, and precepts that need to be communicated.
That is to say, the reader can dive into a set of documentation to read more detail, or, they can step back out to see the bigger picture. As most developers identify as self-directed learners, the goal is to make it easy, fast, and intuitive for them to answer their own questions.