What’s documentation? Why is it essential? What makes it good or unhealthy? And – if it’s unhealthy – what are the results? On this article, I’ll talk about all of this, clarify how documentation (good or unhealthy) is an outgrowth of organizational tradition, and recommend some methods you’ll be able to work to enhance tradition and produce higher docs – even within the face of organizational resistance.

What’s documentation? And what does it do? 

One of many major issues documentation does is information our customers. Studying docs is a essential a part of consumer expertise. You may consider documentation as beginning down within the code, with feedback; then climbing a ladder by means of end-user product guides and have maps, set up, consumer onboarding and QuickStart guides, recipes and examples of use, and extra intensive tutorials.

Past this, you should still be speaking to main customers, however typically to potential prospects, too. Coherent documentation additionally tells a technical and enterprise story about your merchandise in context. It talks about advantages of your merchandise, differentiating from competitors and establishing thought management.

An excellent documentation tradition treats docs as a foundational side of each advertising and marketing and product. 

Why is nice documentation so essential? 

Good documentation makes for:

• Higher onboarding, each for purchasers and new workers. Good first impressions of docs result in good first impressions of your merchandise.
• Sooner troubleshooting, as a result of all the pieces is written down, which helps retain customers and prospects.
• Improved productiveness for purchasers and in your help workforce. Good docs result in good product experiences. They stop errors and confusion on prospects’ components (decreasing help burdens) and allow sooner drawback decision.
• Higher change administration, pretty much as good docs element the historical past, enumerate the impacts, and enable you ship new options with out stressing customers or help people.

It additionally makes for higher communications and fewer wasted labor. Per a current examine by Cornell College of pros working in distributed groups:

• 61% say it may be laborious to determine what their colleagues are engaged on.
• 44% say that siloed digital media instruments made it laborious to identify if work is being duplicated.
• 62% reported lacking alternatives to collaborate with their co-workers and obtain higher outcomes.

Unhealthy documentation is a part of the issue, right here – which is basically one in all communication. Good documentation, if rigorously maintained, can break down communication silos, remove wasted work, and assist your individuals collaborate significantly better.

What makes documentation good or unhealthy?

Good documentation is:

• Centralized in a single platform:  Unhealthy docs are fragmented and laborious to seek out and align.
• Straightforward to grasp: Good docs reduce use of jargon and hold language easy (not everyone seems to be fluent in English).
• To the purpose; It doesn’t let you know a complete story earlier than attempting to let you know what you have to do and what you’re truly searching for. 
• Good visuals: Individuals inherently have a look at issues which are good to take a look at. We wish to have a look at them extra and we wish to have a look at them longer. 
• Straightforward to learn: In case your documentation is troublesome to learn, individuals aren’t going to be inclined to spend as a lot time taking a look at it as they are going to, when you’ve got very properly designed, properly laid-out documentation with fascinating issues to take a look at. 
• Full, correct, and up-to-date: There’s nothing worse than undocumented product options, or docs filled with inaccuracies.
• Contains date and creator: If there are any accuracy issues, we all know once they had been launched and the way they occurred. We additionally know the way outdated this documentation is that if we run into an error. 
• Addresses the proper viewers: Should you’re focusing on the top consumer, ensure that that’s the one that’s getting this data. Should you’re focusing on directors, be sure you inform them which data they should know.
• Freed from assumptions about what customers know or can do. Good docs level customers to introductory assets and guides that assist put together them and provides them inroads to an excellent expertise together with your product. Unhealthy docs sometimes presume quite a lot of pre-existing data. The worst (and we’ve all seen these) appear to be written in order that solely core engineers engaged on the mission can perceive them.

The place do unhealthy docs come from? And what do they value?

Unhealthy documentation cultures share some hallmarks:

• Documentation is all people’s drawback and no one’s job.
• Specialists (e.g., builders) aren’t incentivized to assist construct and enhance docs.
• The group (documentation specialists) aren’t accessible to assist specialists with the writing and modifying.
• Docs are presumed to be deliverable with tasks, however no assets or time are allotted to make this occur. Neither is the necessity to hold docs up to date ever budgeted for realistically.
• Individuals hoard data – to protect job safety or just because no disciplined course of for extracting institutional data and turning it into documentation exists.

What do documentation failures value? Quite a bit. In response to a current article by ItGlue, it’s widespread for workers of know-how firms to spend as much as 20% of their time looking for details about their very own firm’s merchandise. If we assume a median wage of $60,000 a yr, time misplaced per worker prices $13,760, with the chance value (depending on projected worker contribution) sometimes a lot increased.

How do you begin fixing a foul docs tradition? 

In a case examine from Google composed in 2016, 48% of Google engineers cited unhealthy documentation as their primary productiveness subject. 50% of SRE points cited issues with documentation.

What labored for Google was altering the established order. They made documentation radically less complicated for his or her engineers. They made a system that they known as g3docs that did the next:

• Eliminated selections, presenting one strategy to doc issues. 
• Centralized and supplied a single supply of reality and docs instruments. G3docs hosted their docs within the supply code in Markdown, in order that their engineers might keep of their IDs, and work on the documentation on the identical time. Their documentation system routinely rendered out that markdown into good HTML pages. 
• Leveraged the only supply of docs reality – the g3docs workforce shaped alliances with influential engineers to introduce the brand new docs tooling and partnered with particular groups to construct strategic integrations, in order that many tasks might draw on the centralized docs repo.
• Launched and iterated the documentation system within the open so that everyone knew what was happening.
• Had groups lead by instance. Relatively than forcing groups to make use of the instruments, they reached out to a few of their most influential workers to get all people on board.

Strategies for tradition change

Tradition just isn’t immutable. We will change it, however you have to begin from the highest, select somebody to drive it, and make it simple. 

• Begin from the Prime: Begin with standardization, and empower your contributors by establishing that clear, concise writing is the expectation from everybody. To do that, make sure that your higher-ups and your stakeholders lead by instance, with high quality writing. 
• Select somebody to drive it: Make somebody chargeable for managing documentation. Even when it isn’t that particular person’s whole job, make it somebody’s official accountability. This particular person will even create templates, coaching, and some other help that’s wanted to create the documentation. 
• Make it simple: Select instruments that combine into present workflows. Let builders keep of their editor. The extra you’ll be able to let individuals keep within the circulation that they’re in, the extra work they’re going to have the ability to do. And use model management like Git, so that everybody can contribute simply, and ensure that everybody has entry. 

Instruments and methods

These are some examples of documentation instruments that I actually love, and which are extremely popular:

• Markdown is without doubt one of the hottest languages for writing documentation. The Learn The Docs platform is admittedly nice. They permit for the next two documentation methods: mkdocs, which is a quick and easy documentation generator, and Sphinx, which is a extra highly effective documentation generator that’s actually good for technical documentation. 
• GitBook is a pleasant platform if you need one thing that’s not open supply and is a bit more shiny. 
• Confluence, which I really feel like everybody makes use of for his or her inner documentation whether or not you prefer it or not, is a extremely strong system, although additionally not open supply.

Empowering your contributors to make use of a system that enables for contributions from everybody is without doubt one of the causes issues like mkdocs are so widespread: they permit for everybody to contribute. And nowadays, you don’t even want to have the ability to edit Markdown in an editor – you need to use GitHub or GitLab. Their inline editors are completely, completely serviceable for issues like modifying documentation. 

Give coaching on the right way to write docs in case your workforce appears like they don’t know the right way to write or they’re not good technical writers. This may enable everybody to have a way of possession over the docs and take satisfaction in realizing that persons are studying your documentation. Create a constructive suggestions loop for individuals who have traditionally been immune to writing documentation and determine to start out writing it. Just be sure you thank them that you just inform them they did an excellent job in order that they’ll wish to do it once more. 

If it doesn’t work? There are some things we will do. We will go the marginally extra forceful manner and simply not settle for merge requests that don’t embrace the documentation updates. Make an expectation that the documentation is simply as essential because the code. You can even make doc writing an official a part of everybody’s job description. Make everybody really feel the necessity to replace the documentation and get individuals to grasp that that is the way in which that individuals use your product and the way they’re going to grasp it.