Documentation Questions from the MOps-Apalooza Conference

As I am working on several presentations for conferences and webinars this year, I wanted to revisit the excellent questions from the in-person and virtual audience at the MOps-Apalooza 2024 marketing ops community conference.

Some of these I answered during the presentation, but since I am not great at clear explanations off the top of my head, and I was flustered a bit from the slides crashing for a large portion of the talk, I wanted to provide better answers. I answered some of the questions on LinkedIn, and now I want to make the answers more findable in one place.

Topics of this documentation session

How many links are too many links, within documentation?

Let's start with this great question I received after the session from an audience member, and coincidentally, I also heard it in the workshops I hosted the week after the conference.

“It depends,” of course, is the correct answer here. ;)

If you’d like a specific percentage guideline, a good indicator may be if you’re scrolling through a document and it looks like 50% or more of the text is links. The best way to do this is to ask the documentation users if they think it has too many links to be a useful document. When in doubt, don’t guess, ask the users!

Other considerations are if the links take them off the ‘page’ or if they are anchor links within the document. 

Good reasons for internal links within the doc:

• Having a lot of anchor links can help people skip down to relevant sections, such as in a table of contents, or create a quick ‘reference’ summary checklist at the top of a document, and then you have sections with more details later on in the document, linked.
• Anchor links also help ‘link’ people directly to that section of the document. When you send a message to people answering their questions, they don’t have to scroll around looking for what you are talking about. 
• If this table of contents goes ‘below the fold’ on a standard laptop screen, that is probably too many links.
  • Break up the document into larger sections, such as sections/subcategories of the steps, instead of linking every step in the table of contents.
• Conditional processes – “If this happens, do A. If that happens, do B.” Use anchor links to link down to the A or B steps.

Good reasons for using external links:

• You could create separate docs for each type of user, and manually link the documents to each other.
  • As a tradeoff, this can generate more maintenance for process changes but give more usability and personalization for the user.
• Consider linking the article to alternate formats such as a checklist/spreadsheet, meeting agenda template, research template, or project management task template, when it makes sense.
• If you use two main knowledge bases or storage tools for different tyes of users (such as developer/engineering vs. other teams), then link the related docs to each other, so everyone knows when to update both docs for the (hopefully few) repeated processes, or to note when changes to one process affects the other.
• Include a FEW links at the bottom of each document for relevant resources if someone’s questions haven’t been answered yet.
• If the process in this doc is commonly miscategorized or comes up in the search for many different topics (e.g., ‘onboarding’ could be employee, customer, or a service…), add a link to that other process at the top.
• Add a link to the top and bottom of the process steps for the process/task that occurs immediately before and after this process.
• You could create a specific “start here” document, which lists out all relevant documents for learning about a topic, creating a learning path. This document would be more than 50% links. Label/name these types of documents consistently, so people know the format is going to be mostly links.
• Linking to the software company’s knowledge base can be helpful in some cases, so you don’t have to update the details on how to create specific changes in the tools, as those platforms change daily.

Try to embed instead of linking:

• Videos, Looms, process maps, etc – but be sure to specify in the text if the video is the same or different content from the text descriptions.

Speaking of links, during the quarterly review of documentation, check for broken links and fix them.

Many of these tips are hacks if your knowledge base tool doesn’t do these functions well with tags/categories/searching, or if you’re not ready to upgrade to a knowledge base yet. We all start somewhere!

I would love to add to these tips and guidelines about linking!

What advice would you give?

Comment on the LinkedIn Post here.

How do you explain how documentation and training are both useful and not redundant?

Documentation is an element of training, but it is not training by itself.

Training should include a more comprehensive curriculum (an order of learning topics) and a variety of formats. Including a space for questions and checking the comprehension of the topic.

Documentation is a great way to follow up with self-service learning and problem-solving after training.

Remember that not everyone is an ops person who likes to figure things out for themselves, or is used to figuring things out using minimal documentation, like from software companies.  Many people prefer more structured training programs.  Not everyone does well using only the self-motivated asynchronous learning done through reading documentation.

Having both training programs and documentation is ideal.

It may be easier and faster to refer back to the document, instead of watching a whole training video again, especially if you use the internal linking strategies outlined above.

When you come into a company, and they are under the idea that they only need documentation as training -- What do you do?

First, celebrate their achievements in documentation, that is a great step towards building training programs and a helpful next step for reinforcement/maintenance of the knowledge after training (see above). Many companies do not have documentation that teams can easily access.

If their documentation is already available in multiple formats, such as with video or process maps embedded in it, you would be closer to having the elements you need to create training. But people need to be reminded that the documents exist, and reminded why it's important. They are probably going to need to ask questions to fully comprehend and feel confident in this new topic they are learning about.

Asking questions and having human support is especially important for onboarding and other new hire or new process trainings.
Not just handing them a pile of docs.
Though docs are helpful for empowering people to self-serve answers to some of their questions, so they don't have to ask every question to a human.

Having both documentation and training is a powerful combination that will get the company the most results from what they want their teams to learn and do.

Where did I work that had this kind of system? What magical industry was this?

The core of this system was from the marketing and revenue operations agency I worked at, but this ideal documentation system has evolved after talking with people in my classes and other research I've done since that time.

That agency was fairly small, 10-25 people on average,  so many people had many of these roles discussed in the system.
Separating out the roles should work better for larger companies, since it distributes the work more to not overwhelm any one person.

Learn more about roles here.

An important reminder from the presentation!

How do you improve existing systems once all documentation is 1-2 years old?

This is such a great question that I address it in my classes, which means I also have a blog ready for you to read about it!

What documentation tools track usage, such as who is viewing each document?

I don't try to be a software expert, so off the top of my head, I didn't know.
The audience mentioned that maybe Confluence did that, but they wouldn't recommend that choice overall.

Back in my agency days, HubSpot's knowledge base would show how many people were viewing the page, and I believe the time spent on the page. But I believe it only showed front-end views, not the back-end editing views that many of our team members had access to. And it did not show which specific people were viewing it.

A quick Google search reveals that these common tools can track who views each page/document:

• Notion 
• Trainual 
• Clickup Docs 
• Guru 

Do you have suggestions for document navigation, such as naming and folder conventions?

For naming conventions, I like a "how to" or question format to mimic people's search habits.

Another good format is to use a verb at the front of the name, to ensure consistency without getting a 'wall of how to" in the search results.

If you have many similarly-named or confused processes, you might want to put the department name at the front of the name, such as "Marketing: Create an email newsletter."

For an example of categories or folders, at the agency I worked for, we had department names as the top level of folder or category, with an additional category of "ops for everyone" (as an ops agency we encouraged the use of the word) for those hard to categorize processes that span all departments and aren't identifiable as just HR. Those cross-functional processes can be hard to categorize into a department name, so I would love to hear how other people have overcome this challenge and decided where to categorize them.

Additional navigation and searchability topics to consider related to documentation:

One reason I suggest you use or integrate documentation into tools your team already uses is so they can use the same navigation or search function they are familiar with to find what they need.

• How can your documentation storage mimic the navigation and searchability of other systems your users are familiar with?
• Can you use tags or another method to make sure any alternative phrasing of the process/question will still retrieve the correct articles?
• Have you surveyed your documentation users to collect the different verbiage used to describe the same processes?
• Can you set up their permissions so the user’s default view of the storage area is the category most relevant for their role? (Fewer clicks)
• Can you include the best practices for searching and navigation in the “How to use the knowledge base” doc that you should have created? (training them, not assuming they can figure it out. Non-ops people don’t often like to figure things out themselves by trial and error, especially software.)

What do you do when people say they think another way to do the process is better?

This is a fairly common objection to using documentation, though often it is not said out loud or directly. It is similar to the question I receive in classes about people not LIKING the process in the documents, and that's why they are not using it.

Approach it from a place of curiosity.

Why do they think their way is better?

What is 'better' about it? (Is it faster? Does it achieve better results? Or is it just how they are used to doing it?) 

Have they tracked the results of doing the process both ways? If not, you could possibly set up a test of that.

Who created this process? Did they involve the team and build in public to get everyone involved and bought into doing the process this way? (probably not, or this is a new hire's question)

Does the documentation explain WHY the process is done a certain way and what has been tried (and failed) before? That context is always good to add to documentation, so it's not just a HOW document but a WHY document with human context.

Is the process owner or manager monitoring and managing this process? Do they know this person is completing the process a different way? What do they say about it?

Can you and the process owner/manager agree on the places in the process that are flexible, and the places that the process must be done in a certain way? Find a way to notate that difference in the document, if so.

Have you explained what's in it for them to complete the process in the documented way?
What do they care about? Being faster, not having as much work? Or maybe they want to be more effective with the process?
Tailor your answer to match what they care about related to completing this process.

How can you create learning paths for internal use?

An easy way to start could be by creating a document that is named something like “start here to learn xyz topic,” then inside that document, you are linking to content in the order you suggest they complete it.
This can help you start wrangling all that content together in an easy way to begin with, then create a more technical solution within an LMS later on.

An LMS is not going to magically know which content to recommend on a topic and the order, those are all directions or instructions you'll need to input at some point when you transition to a new tool.

Which paths do you create first?
To decide which role or path to start with, perhaps see which role is onboarding next, or onboarding the most at your company.
Think about: what do they need to know first to do their role when they are onboarding?
The onboarding program I created first showed what you need to know on your first day, then mostly company information for a few weeks, then role information, then the technical day-to-day work or training.
Make sure the learning paths also contain human interaction, not just watching an LMS all day, every day for weeks.
Meeting the team, meeting leaders, talking to humans every day.

Another way to decide which path to create first may be to do a needs analysis to find what topic or path people need more structured training on. Where are their pain points, frustrations, common errors, and reasons why they may not be achieving their goals? This might be a cross-department, company-wide learning path as opposed to a role-specific path.

Thanks for asking these excellent questions!

You can read about the sessions at the MOps-Apalooza conference here:

• Conference Day 1
• Conference Day 2

I have on-demand and live classes about documentation if you'd like to learn more!