Decentralizing responsibility for company knowledge

Much of what the DevRev product contains was informed by experiences creating the systems and processes needed to operate Nutanix. Knowledge management is one of those areas. As with customer success, DevRev democratizes knowledge management in the product and in our own practices.

The knowledge ecosystem

No single content domain is the comprehensive source for product knowledge. Product documentation for users or developers is a large part of it of course. Other obvious significant domains are the support knowledge base, in-product copy, solutions documentation like reference architectures, technical marketing, and training. There are still others, including competitive briefs, implementation guides, messaging documents, blogs; and the list goes on. Not all domains are relevant to all people; nor is is permissible for all people to have access to all information. Still, to take a broad view of knowledge about a company and its products, all these domains must be included.

One implication is that all pieces of information, however they may be defined, have a lifecycle that ends with deprecation. It’s easy to create or duplicate information; it’s much harder to know when to deprecate something, or “de-accession” it to use a term from library science. Take a brand guidelines document for example. If a new document is created, then the previous one has to be de-accessioned, or people may ignorantly continue to use the old one.

The centralized operating model

While Nutanix was innovative in many areas of technology and business, it was pretty traditional in the organization of the documentation team, which I led for 10 years. We were in engineering, reporting to VPs of hardware, and all the technical writers were in this organization. In this traditional, centralized operating model, the tech pubs team is responsible and accountable for updates to the docs—docs is a product, and tech pubs owns that product. Practically speaking, the tech writers spend a large portion of their time monitoring development activities, attending weekly meetings where there is a small but non-zero chance of learning anything useful, and begging stakeholders and SMEs for input and feedback. This puts the tech writer in the position of asking for help from the stakeholders rather than the other way around. Only the tech writers can make updates to the docs, often because expensive and complicated systems are used. So in the cases where a product owner is actively seeking updates, they have to work directly through the tech pubs team. This often means that the tech pubs leader has to allocate resources, which may mean a change in prioritization or a delay in getting started.

At the same time, there were multiple centers of product information that were necessitated by content management and delivery considerations. In addition to engineering with the tech pubs department, the support team had a group managing the knowledge base; marketing had a team to create white papers and other technical marketing assets; the services org had customer education; and solutions engineering also had a publications team that created best practices and reference architectures. Now all of these teams were all capable in their own right, and we mostly agreed where the boundaries should be. Still there were plenty of cases where certain organizational requirements led to contradiction.

To take one example that happened occasionally, consider a slight misconfiguration in a product setup. The customer contacts support, who refers the customer to the documentation and directs them to make the update. Now it is discovered that the documentation mostly fits this situation, but it would be more usable or discoverable with an additional detail. As the tech pubs director, my suggestion would be for the support engineer to file a request to have the documentation updated. But this is overhead for the support engineer, and it may take a week for the documentation to be updated. Instead, the support engineer copies the chunk of documentation, makes a few small changes, and publishes it as a KB article. Then in the next release, the product requirements or interface changes. The documentation gets updated, but the KB article doesn’t. Customer confusion ensues—creating a short-term solution also created a long-term problem.

Traditional documentation models are engineering-oriented and one-way. Tech pubs is often a part of engineering, and the primary subject-matter experts (SMEs) that the tech writers work with are engineers. The audience for the documentation comprises support and customers. While tech writers are usually eager for feedback from the users, organizationally, that channel rarely exists. Once a doc is published, there usually isn’t any good way of evaluating whether it’s meeting the needs.

Customer feedback

While many docs sites have a “give feedback” or thumbs up/thumbs down, the amount of actionable feedback is somewhere between low and nothing. And no wonder—typically there isn’t a way to close the loop with the user. So on the rare chance that a user has something useful to say and the motivation to say it, they’re most likely just sending their words into a black hole. If you talk to tech pubs directors about feedback widgets, you’re likely to get eye-rolls, groans, and nervous laughs.

“Sure, we’ve had a feedback widget for years,” they’ll say, “but we’ve never once learned anything useful from the very few pieces of feedback we’ve received.” Do you follow up with users who give feedback? “No, we don’t have any way of correlating feedback with customers, and even if we did, we wouldn’t have any way of communicating with them directly since that all has to go through support.” I was quite disturbed once to hear from several people that they were explicitly prohibited from talking to customers! Support, success, or sales is considered to own customer communication, and no one else is allowed. If a tech writer would want to talk to a particular customer, their only path would be to attempt to get on the agenda for a customer meeting. Rarely would it be considered important enough to address.

While I was skeptical for these reasons of adding a feedback widget to the Nutanix docs site, it was being proposed by my excellent manager of the Tech Pubs India team. I didn’t want to stand in the way of his initiative so gave my support. To give away the ending of the story, we did get a lot of actionable feedback, and I was able to brag at conferences that our feedback program was successful. No doubt a lot of that was due to the overall customer feedback culture that Nutanix had cultivated from its infancy.

Even so, I don’t think it would have been successful without one piece that we considered from the very beginning: how to handle the feedback that comes in and how to follow up with the customer. Docs were hosted on the support portal, so if an authenticated user gave feedback we could capture their email address. For non-authenticated users, they were given the option to enter their email address. All incoming feedback was emailed to the managers for triage. If the feedback indicated some change to be made to the docs, a manager would file an issue and assign it to the responsible tech writer. The goal was for the necessary updates to be published within a week. Crucially, the tech writers could ask clarifying questions if needed, and they were also responsible for communicating the update to the customer. Not infrequently a customer responded with surprise that their feedback was addressed, let alone that it was communicated to them. And more than once, we had a customer submit more feedback within a week or a month since they had confidence someone would follow up.

Knowledge-centered support

On the dimension of customer feedback, support has a superior process with the notion of “Knowledge-Centered Service” (KCS). While it is a comprehensive formal methodology, in summary:

KCS is a proven methodology for integrating the use, validation, improvement, and creation of knowledge into the workflow. Inherent in the methodology is a process of continuous improvement that is based on the experience of those doing the work and the patterns that emerge from knowledge reuse. KCS is very different from the traditional knowledge engineering approach, which is based on the concepts of knowledge from a few for the use of many. KCS is a many-to-many model. Its elegance stems from the fact that it is demand-driven and self-correcting.

Principle 7 of KCS is “Collective ownership: Leveraging the best we know to date”. It defines two “loops”: “The Solve Loop is the task at hand. The Evolve Loop is the collective experience of all those tasks.“ The solve loop tends to generate content and delivers near-term value; the evolve loop treats the content as a business asset that has long-term value.

The collective ownership aspect is key. Knowledge is distributed throughout the organization—among developers, support engineers, customer success managers, consultants, partners, and customers. The goal should be to capture useful knowledge, regardless of its provenance, and make it available to whomever would find it useful.

A few weeks ago I came across a discussion about tech writing in the age of AI. Someone commented that tech writers would now be doing knowledge management. My immediate reaction was to ask if tech writers weren’t doing knowledge management before, then what were they doing?

The requirement for evolving brings in the dreaded g-word: governance. Far from reducing the need for governance, drawing ecumenically from any sources of knowledge increases the need for governance.

The distributed responsibility culture

At DevRev, the operating model is inspired more by KCS than by traditional technical publications. It’s more of a culture than a strategy. Rather than docs being a product that is owned by tech pubs, docs are a necessary dimension of products that are owned by the Product organization. In this model, the PMs are accountable for the docs for their product, and they share responsibility with the Knowledge, Support, Customer Success, and Engineering organizations. In the case where a new feature is GA without the attendant docs, it’s PM who is asked when the docs will be ready, not the tech writer who is asked why they didn’t know about it.

There is still a range of levels of assistance the product owners need with the docs. Sometimes, PMs are thinking ahead and start discussing with us weeks or months ahead of time; other times, the product goes out before docs have been considered. Sometimes, the product team delivers thorough, well-organized docs that need only a few superficial changes before they are published; other times, there is only a comment in Slack or a brief outline in Google Docs to get started. The important thing is having a motivated stakeholder who takes responsibility.

A crucial bit of support is automated language checking. Since the contributors do not spend all their time thinking about terminology, style, and grammar like tech writers do, their input may not meet the requirements in these areas. At the same time, human editors can burn out or be a drag on velocity. To address this need, we have an automated language checking utility that runs as part of the GitHub pull requests. It uses the style and terminology rules we have configured and makes comments and suggestions on the changes for the author to review. Then by the time a member of the Knowledge team comes to review, small and routine errors have already been fixed.

Once the tech writers are seen as supporting the product owners rather than the other way around, the dynamic totally changes. One place where this difference is visible is in how issues are organized. In the centralized model, most products had their own project in the issue tracker. Infrastructure, including docs, was in the general ENG project. Within ENG, the “Documentation” component was structured as a product with subcomponents for different products or projects. To make a request for a doc change, someone would file a request in the “Documentation” component of the ENG project. This request would be further categorized and assigned to the appropriate tech writer, either by default or during triage.

In the distributed responsibility model, work items (either issues or tickets) are filed in association with a part whose default owner is in fact the product owner. The product owner now has awareness of the concern and can prioritize and take the appropriate action. An added benefit is that the work items are often linked to customer tickets. In this way, context is preserved. The context informs the work of the tech writer, and the customer can be notified when their concern has been addressed.

Contrasting the two models in the RACI framework, looks like this:

Information process maturity model (IPMM)

In the 2000s, JoAnn Hackos, an expert in the field of information design and the founder of the Center for Information Development Management (CIDM), described a maturity model for enterprise information management. While it is dated and limited in some ways, it retains a good amount of utility. The IPMM has five levels of maturity, summarized below.

At DevRev, we’re using the IPMM to get a sense of where we are on this journey. In a couple domains I think we can honestly say that we’re at Level 3, but most are Level 1 or 2.

One of the limitations of the IPMM is its department-level focus. It assumes a centralized information-development organization that ultimately absorbs all others. This view is at odds with KCS, and as described above I’m more keen on the KCS perspective on this question. It is not, however, a fatal fundamental flaw in the IPMM, just a point of adjustment.

What’s needed is not an expansionist organization, but a small program management function or center of excellence that works across domains. At Nutanix, we achieved a certain level of success with grassroots coordination. There did come a time, however, when that wasn’t enough. Despite everyone’s interest in doing so, all organizations were stuck at Level 3 without a way for all to move forward together.

Content management and delivery

While “content management” is a well-established term, it often incorrectly subsumes the separate notion of “content delivery”. In every situation I’ve been in or have heard about, the content management system (CMS) is separate in some way from the content delivery system (CDS). At Nutanix, we used the OASIS standard DITA for the source material stored in Git and later GitHub, authoring in a proprietary XML editor, and publishing HTML to the custom-developed support portal. GitHub plus the authoring tool was the CMS; the support portal was the CDS.

This is not unlike the landscape at DevRev. At present we are taking a docs-as-code approach, which enables distributed responsibility. The source content is markdown files in GitHub, authored in VS Code or the GitHub web editor, which is published to a custom-developed docs portal. Once we’re able to move completely into the DevRev app, the split between the CMS and CDS will still be there. The DevRev app knowledge base will be the CMS, and the customer portal will be the CDS.

It’s not true that a CMS is a system that manages content for you. Rather, it’s a system that enables you to manage content; if you’re lucky the CMS makes it easier. Put another way, content management is an activity, not a tool. Moreover, the last two decades’ dream of a single enterprise CMS that can be all things to all people is clearly never going to come to fruition. Instead, CMSes proliferate, while the one CDS for customer-facing information has to be custom developed. Mapping multiple CMSes to one CDS, while necessary, is challenging for information architecture.

Conclusion: Taxonomy and ownership

In DevRev, everyone is using the same taxonomy. Tickets, issues, articles, and other objects all link to the parts that have been defined in the app. Moreover, although there is a native object for articles, the ingestion layer easily handles disparate content management systems. Today we are able to ingest web pages from the docs, blog, case studies, and Book of DevRev in addition to documents in Google and Notion that are linked to parts. Each part has an owner who then implicitly own the articles associated with the part. This ownership is the crux of distributing the responsibility for customer-facing information.