A recent CodeProject survey showed that the biggest impediment to learning a new technology was poor documentation.  When Evans Data Corp asked an even wider audience of developers why they had rejected proposed and even purchased tools in the last year, as many developers cited a lack of adequate documentation as did cite poor integration with their existing environment (28%).

When the modern developer, IT professional, or DevOps engineer is trying to learn or evaluate a new technology or tool, public documentation is among the content they use to inform themselves. They also use public documentation to help them maximize their existing tools.

That’s probably why you recognized the importance of having public documentation become a part of your content marketing campaign. Since this is the first face of your product or company a developer prospect sees, it needs to be a good one. That’s why your public documentation deserves to be part of your content marketing strategy. That’s possibly also why you are gnashing your teeth. Now that you own public documentation, how will you guarantee that it is well-received by your audience?

The Pillars of Excellent Documentation

The one thing you can say about excellent documentation is that excellent documentation is not just one thing. It contains several different types of resources, and it is organized so it is easily navigable. Easy search and scan applies equally outside and within the documentation itself.

  • Organization

On your public documentation landing page, make sure to include an “at glance” overview of the key documentation you provide — by stack, by application, and by key components. The documentation itself includes an at-a-glance overview of key points covered in that piece of documentation.

  • Style

The style should be direct and to the point with a detailed-enough description to make the information searchable and easy to skim. Succinct, descriptive headings with slightly more detailed summaries, followed by the more-detailed content needed for implementation appeals to an audience that is anxious to answer a question as efficiently as possible.

  • Content

Content writers like Oana Mancu and Roger Deutsch, who focus on simplifying information to step-by-step instructions, example code, and images, understand these mechanics of teaching.  Programming can be intuitive, but, “…documentation creates a narrative where the code fails to…” according to Deutsch. These developer authors understand instinctively what the data bears out.

Psst…Buddy…Need Some Public Documentation?

Oh, don’t you wish someone would ask you that? Instead, you fought to create the documentation. Now, well, it’s time to execute.  Perhaps you already tried to tap into your product development team, only to find that they think they already did the documentation. And, they did… for another member of the team who already understands the product. Not for the developer struggling to get started with something they have never used before.

It’s Time for Some Developer Empathy

You don’t have it, your product team doesn’t have it, and you probably can’t easily hire it. You can try and build a developer community and rely on their empathy, but that takes time, energy, and even more money. However, there is some truth there.

Why? The practitioners sitting outside your company are less likely to make assumptions because they aren’t a product creator. And they are more likely to understand where someone new to the product is likely to need things spelled out.  Finally, they can be a good source of sample applications, because they are not constrained by the boundaries of the product development mindset.

Practitioner Content Marketing to the Rescue!

If only someone created high-quality technical documentation as a service! What, what, what… There’s a lab for that. ContentLab.IO is a tech content-as-a-service company that delivers all the dev empathy you need from practitioners who write for their peers. Serve up their solution, and solve your audience’s problems by giving them the documentation they need for everything from a feasibility study to solving a post-purchase problem.

That’s a Wrap

There’s always an answer, and sometimes, it’s the write one. 😉 Producing high-quality public documentation feels hard because it is hard. Stop trying to flog your product development team into doing the marketing, and leverage the wide-eyed innocence of the practitioner outside your company. You don’t have to find them or manage them.  Just use a service that does, and bring in the new dawn of developer documentation satisfaction.