Final thoughts on enterprise documentation

(Note: When I wrote this article I thought I was going to stop working on enterprise documentation to work on Inner Source. — Turned out, I’ve been given the opportunity to work on both!)

In this article, I share some of my thoughts about enterprise documentation to wrap up my experience as a documentation PM — For the past year and half, I have been working on enterprise documentation solutions. Starting this week, I will stop working on documentation and start working on Inner Source at Microsoft.

Documentation is not just a Reader problem, but also a Writer problem

The purpose of documentation work is to improve productivity, which is only achieved after the information flows from the Writer to the Reader. This means it is important, as an enterprise documentation PM, to not only provide a great search & read experience for the Readers, but also facilitate the creation of documentation from the Writer’s side.

Who are your Writers? Where does the information you service come from? Depending on the answer, you might be servicing a primary, secondary or tertiary source of information. In enterprise settings, I assume most of the time you service a primary source, because the documentation are original work authored by your colleagues (and later consumed by your colleagues, too). This effectively means many techniques employed by secondary source services (such as Quora) or tertiary source services (such as Wikipedia) to improve won’t apply to your service, because those services can rely on a crowd of enthusiasts and fans, who paraphrase existing literature to provide the content, but your content has to be original.

This originality creates the problem of ownership, as the corollary of this originality of content is that there are only a handful of people (namely the subject matter experts, SMEs) who can take care of this content. Therefore, enterprise documentation, unlike public information services, needs clearly defined, well-maintained ownership, in order to uphold accountability and content quality. The curation of enterprise documentation generally cannot be crowdsourced; it has to be owned by the right SMEs.

Documentation is not just a Technology problem, but also a Culture problem

But just because documentation ownership needs to be taken doesn’t mean Writers will prioritize it. Quite the opposite: in my experience, documentation work is usually treated with lower priority. A popular belief among engineers in various companies is that their job is to write code, not documentation. I see three reasons behind this:

  1. The impact of documentation work only manifests in the long term: compared to code, documentation might be consumed much longer after it is produced, and it usually takes a while for the Writers to receive feedback on or gauge traction of their documentation work.
  2. Documentation work is, in its nature, less creative than coding. Coding is creating something that didn’t exist before. Documenting stuff is repeating what you already created.
  3. Writing documentation is not considered part of the job description. Engineers think they are hired because of, and evaluated based on, their ability to write code — not documentation. Managers are happy as long as code is being pushed out, because tribal knowledge usually suffices as long as the feature team is still there to service the project — and that doesn’t change that often.

This creates the impression that documentation is optional, tedious and thankless. To battle that impression, a documentation PM needs to work on not only providing a great Writer experience, but also promoting a culture where everyone is committed to write quality documentation.

Among the three reasons I observed above, the first one is probably easier to attack when building a documentation culture. For Writers, understanding the impact of their documentation helps build momentum. If the documentation PM can help their Writers see the readership and usage metrics as soon as the documentation is out there, the Writers will be much more likely to invest a sustainable amount of effort into curating the documentation. Everybody likes to know that their work is reaching the consumers, and knowing it in telemetry numbers is better than knowing it by waiting for the consumers to reach out and say ‘thanks’.

Documentation is not just an Experience problem, but also a Content Quality problem

The Reader’s experience is made of two parts: the Platform Experience (is your documentation platform easy to use?) and the Content Quality (is the hosted content accurate and well-written?).

A feature PM solving documentation problems may choose to focus on Platform Experience, delivering a great platform with nifty features and smooth user experience, but for the Reader customers, Platform Experience and Content Quality are two sides of the same coin that cannot be separated. Reader’s perception of the documentation experience depends on the combination of both: no matter how great your Platform Experience is, if the content is all outdated, it will still fire up DSAT among Readers, because poor documentation quality undermines Readers’ productivity.

It might take a while to recognize that these two are separated issues, and a good Platform Experience does not automatically imply good Content Quality. When I look at what the unsatisfied Reader customers say about the platform I worked on, I see many reported cases where the Platform Experience is outstanding (which I am proud of) but the Content Quality needs a lot more work. Guess how do these customers rate their overall documentation experience? Always a thumbs-down. After all, a documentation PM solves documentation problems for their customers, and the solution cannot be great without great content quality.

But this is where it gets a bit tricky: documentation PM’s can’t own Content Quality, at least not directly. Unless the PM role is also a technical writer role, it is up to the Writer customers to create and maintain the documentation. This is where the aforementioned attention to the Writer’s experience and documentation culture needs to be paid — the documentation PM’s job in this aspect is essentially to help Writers help the Readers get high-quality documentation.

Then, on the Reader’s side, there’s also something worth noticing: in enterprise settings, Readers seek content because it is necessary for them to do their job, not because it is fun to read. This leads to an interesting corollary: rating systems that you often see in public info hubs don’t necessarily work for enterprise documentation (examples of rating systems: thumbs-up and thumbs-down buttons, “was this page helpful?” buttons, etc.) The reason is the lack of alternatives: even if a work documentation page is poorly rated, you still need it to do your job. This is why I believe enterprise documentation services need to be equipped with an “action items” system: just giving thumbs-down isn’t enough; the Readers need to call the Writers to action in such situations.