There is No Perfect “Golden Path”

Respect the fact that even the best designed “Golden Path” doesn’t cover every detail of every position at your company

This is a critical truth which anyone who has worked long enough will recognize. Sometimes employees find themselves confused and unprepared despite their company’s best intentions. They can enjoy the benefit of a comprehensive and thoughtful onboarding, a clear place on the org chart with helpful and available colleagues, and, still, they might find themselves stuck on a problem they can’t quite navigate. That is because a “Golden Path” can’t cover every in and out of the spine of a service or feature. It can’t answer every question and fully prepare employees for where they’ll be responsible for spending most of their time, and, even if it attempted to do so, such a task simply wouldn’t be feasible.

Onboarding tutorials are optimized to give a high-level overview on how a company or team and its workflow are organized. They are meant to provide insight on the big picture, drawing a mental map of relationships between various concepts as well as the motivation behind and importance of their proper execution. These tutorials, however, don’t go deep on how to tackle all the challenges that lie in wait.

Assume that there will always be more questions your employees need answered and look for the most succinct ways possible to answer them

A tutorial may show someone how to build and deploy a simple service, but it will likely not touch on how to debug that service, or how to plan for its capacity needs. A proper analogy is building a house. A General Contractor might spend an afternoon giving you important tips on how to lay a foundation, but would they be able to answer every question that comes up with regards to the different strategies necessary if that foundation is being laid in rocky terrain vs a soft clay vs peat?

This is where TechDocs come in. When implemented properly, TechDocs represent an authoritative, centralized place where employees can easily “unstick” themselves while suffering minimal disruption to their workflow.

Docs Should Protect the Flow State

Use workflow channels to identify places where employees get stuck and processes/operations can be written down and documented.

The benefit of maintaining momentum speaks to one of the major advantages of TechDocs, which is that they grant the user knowledge in the moment they need it. There is no need to schedule a meeting with your co-worker, wait for available office hours, or sit through a video that may provide more information on more subjects than is necessary.

Context switching comes at a significant cost, in time and productivity, when dealing with high-intensity focused tasks. Of course, there are other tools which allow an employee to seek a solution without too much disruption. Slack (or an internal Slack-like service) presents an obvious example; should they get stuck, they could just pull up the appropriate channel and ask their colleagues for advice without leaving the desk or tapping on someone’s shoulder. These options might seem effortless. In fact, though, they come with a high hidden cost.

Make sure your docs are stored in a centralized place where they are easily discovered and easily searchable

Fielding the same questions over and over again, even via Slack, runs the risk of frustrating the handful of people who take it upon themselves to always offer answers. This creates the possibility of alienating these employees and giving them a reason to strategically ignore Slack. Rather than repeatedly relying on their goodwill, it makes more sense to write down the answers to these common questions so that the next person can save time and energy and troubleshoot on their own.

 It is critical to consider the human element when offering this sort of assistance. TechDocs should have a specific point of view and address a specific problem or scenario. They should be well structured and present as authoritative; it’s maddening to go find a doc that addresses a problem, only to second guess whether it is up to date or offers the best possible solution. Finally, they should be well written and stored in a centralized place that is easily accessible and searchable.

TechDocs Work Best When Blended With Live-Learning

Ensure that your docs address specific, tangible problems

Of course, TechDocs are not always the solution. They are most effective when addressing smaller, consistent problems with answers that don’t frequently change. It’s also best if those answers aren’t in need of a lot of context, or if prior context can be assumed. Conversely, they are less effective when the topic being addressed is in flux, or when there are large skill gaps preventing an employee from solving a problem.

In this way, TechDocs operate similarly to a well-staffed library. When someone enters a library looking to read or research something specific, they’re able to count on the assistance of a knowledgeable librarian who can point them towards the right section of books and help find supplemental reading materials.

Subjects and solutions with good docs experience much better traction and adoption than those with bad docs. This is especially true in the open-source world, where there may be multiple OSS projects that solve the same problem. It is often the case that better written and authoritative docs will win over more adopters and contributors.

Keep live events in the mix; TechDocs can only do so much, and employees will always benefit from the unique opportunities that come with socializing.

In spite of their immense utility, it is important to keep in mind that other human beings and live events will always remain a useful guide for navigating certain issues and orienting someone early in their tenure. Even when a doc is well constructed and curated, a colleague or event can help create a space in which people can constructively grapple with larger problems or gain a deeper understanding of critical cultural contexts. Topics such as data science or standing up servers are generally too large for TechDocs to handle all on their own. If we return to the library analogy, few people would be able to get as good an education only making their way through stacks of books as they would enrolling in a university, attending classes, and using the library as an important supplement.

There is no need to create a false dichotomy between docs and events. It’s best to have both in order to boost understanding and speed up learning. Docs complement a well-executed onboarding process by giving an employee the tools to continue learning and problem solving on their own. The question of how to best blend docs and events is directly related to an organization’s maturity and where it sits on the TEMI Index.

A Mature Company Uses Mature Docs

Don’t let your docs creep and morph into monsters

Successfully using TechDocs is an important data point that speaks to a company occupying a higher end of the maturity scale. However, a mature org that is ready to use docs will not necessarily possess mature docs which are ready to be used. This is a crucial distinction, and when a company possesses maturity on both sides, it’s demonstrative of successful Tech Enablement. Investing and developing resources like docs moves companies up the TE Maturity index.

There is no simple, universal test to determine whether or not a company has mature TechDocs, though minimal variance in the quality of onboarding from one cohort to the next is a strong sign that it does. 

So what does a good doc look like? 

First and foremost, it’s critical to ask which type of doc is appropriate for the situation at hand. Authors should clearly identify the problem they’re looking to solve/information they feel is necessary to transmit. Too often, what starts as a simple doc sprawls and morphs into something else, becoming, in short order, a tutorial and then a cookbook. What results is a “Frankenstein” doc that is impossible to both consume and maintain.

Each doc will ideally have a clearly identified audience and a minimum viable product. If the company employs staff Technical Writers, the doc should also have a rubric against which it can be scored and given a “clean bill of health” which communicates that it is complete and ready for use. Docs can even be given a maturity score that conveys how concisely and completely they communicate critical information. 

Be thoughtful when identifying which type of doc to draft

The long-term goal, of course, is to build the structures necessary to create, maintain, discover, and consume answers to the specific, critical questions that can interrupt an engineer’s workflow. The engineers should have tools to draft those docs themselves. Technical Writers shouldn’t be seen as the originator of these docs, but, rather, as an editor tasked with organizing them and providing a final seal of approval.

To close this chapter, then, here are a some of the major types of docs, as well as the situations in which they should be deployed:

• Guides / Tutorials

• • These offer a step by step explanation for how to accomplish a task or operation. They are a great tool for someone who is looking to synthesize and embody knowledge.

• Playbooks
  • It’s critical to offer explanations for how certain technologies are utilized by an organization. New employees might arrive as experts in C++, and yet, be clueless as to how that language is specifically deployed by their team. Playbooks help clarify situations like these.

• Cookbooks
  • This is a doc that reverses the old saying that it’s preferable to teach someone to fish rather than just giving them your catch. A cookbook provides a very specific, easily accessible answer that will allow an employee to stay in their workflow. There is no attempt at teaching a larger skillset in these docs.

• Project Docs
  • They serve to explain what a project is all about and why it exists. Ideally, they will also outline who is contributing to it, how it was set up, and where to report any issues.

• Runbooks 
  • The definition of a critical tool, these lay out how to troubleshoot systems when there is an unexpected emergency. If a company’s servers go down, a runbook should exist laying out the steps needed for employees to get them back online.

It’s Difficult to Keep Docs Concise (But You Really Need To)

Give docs a clear owner/process so they’ll stay on topic, and design so the strongest docs are easy to identify and discover 

As with any tool, building out a robust store of TechDocs does present some challenges. The two most obvious are maintenance and discovery. On an individual basis, it’s easy for docs to suffer from a lack of clear ownership, especially when attempting to lay out a Golden Path that spans multiple teams and systems. This confusion increases the likelihood of them being poorly written and hard to follow, which in turn can turn a doc into the dreaded “Frankenstein”. 

On a collective basis, many companies suffer from a lack of an internal Google. There is no native search function that can surface the best and most relevant doc on any given subject. When an employee goes looking for a specific answer, they may return with numerous results, with no guide on which will be the most helpful or should be read first. While an efficient system of discovery is critical, access controls can make it difficult to both build one out and assess the relevance of any individual doc.

These difficulties are the reason why companies and their employees need to be methodical about where information is stored and how it can be discovered. The principles of information architecture hold true here as they do in so many areas; companies need to be deliberate in organizing knowledge to avoid the chaos of anything goes. They can compensate for searchability by clearly identifying the starting points of topic areas. It should be readily apparent, from the get-go, if an app deals with building services, performing analytics, or deploying apps.