Too many cooks in the kitchen: Successful knowledge base collaboration

There’s a pattern I’ve seen a lot, both in my own work life as a technical writer and in my time here at KnowledgeOwl. You, as the lone person owning your knowledge base, have spent a great deal of time creating content, tweaking the configuration, and producing solid documentation. You’ve felt like it’s been a long, solo endeavor, but you’re finally starting to feel good about the documentation you’re creating.

And then, it happens: suddenly other people have interest.

On the surface, this is wildly exciting: you’re getting buy-in and participation!

But very often, this interest tends to suddenly involve things like layout, design, small tweaks within articles, and so on: what I might call documentation presentation rather than content.

And once someone begins suggesting ideas here, the floodgates have opened.

You’ve longed for other people in the company to be as excited about your knowledge base as you are, and part of you relishes this newfound enthusiasm. But on the other hand, soon you are deluged with many small requests or suggestions--tweaks to the home page, the placeholder text in the search bar, debates about how the table of contents should be styled or why you aren’t using more styled call-outs in articles. The curse of a thousand small decisions and tweaks.

It’s a problem a lot of us face as our knowledge bases gain visibility and traction: suddenly other people are interested. It’s great--you have visibility!--but it’s also awful--now all kinds of people who still aren’t contributing hours to improve things want changes made.

If you are facing this kind of battle--or anticipate you may have to face one soon--here are some tips on how to channel all that enthusiasm in useful ways.

Context: Why is this happening?

There are usually a few different reasons for this interest. In my experience, the influx of suggestions comes from one of two places.

Bike-shedding

You may be familiar with C. Northcote Parkinson and Parkinson's law (that work expands to fill the amount of time you have available to complete it). Less well-known, except perhaps in software development circles, is Parkinson's Law of Triviality: that members of an organization give disproportionate weight to trivial issues. In his original work, Parkinson explained the law through a fictional situation: a committee's review to approve a nuclear power plant's building plans. Though the committee did review the plans, they spent more time debating relatively minor but easy-to-grasp issues--such as which materials to use for the staff bike shed--than on the nuclear power plant as a whole.

In part, this has a little to do with the sense that someone who "knows better" should probably be the one to weigh in on big picture items. As one of my former coworkers put it: ask the team what the company strategy should be for the next five years, and no one will say a word. Part of the group won't have an opinion and much of the rest of the group won't say anything because they either feel they'll be shot down or they don't feel informed enough to offer good suggestions.

But tell them you want to repaint the conference room? Everyone has an opinion and you’ll have months of heated debate. People no longer feel concerned they don't have the context or information to offer opinions. (For more discussion of bike-shedding, see Poul-Henning Kamp's treatise on it.)

So sometimes, the influx of suggestions on small presentation tweaks comes from members of your organization who don't feel informed enough--or expert enough--to offer more substantive content tweaks.

Judging a knowledge base by its presentation

The other influencing factor is, quite simply, that most of us do tend to make quick judgments based on appearances. Consequently, other than finding the content you need, it's often the first element of knowledge base structure, design, and layout that your average reader/user notices enough to have an opinion on.

Tips for managing "presentation" feedback

So what's an enthusiastic tech writer to do when, after spending countless hours producing quality documentation, the only specific feedback she can get is a mass of presentation-related quibbles? Well, here are some techniques that have worked for me in my time as a technical writer and product manager.

1. Remember who you are

As with any product or service, once a chorus of voices starts offering suggestions, feedback, input, guidance, or demands, it can become very hard to prioritize that data and act upon it. You can feel overwhelmed and pulled in a thousand different directions.

One of the best methods I've found to combat this is to have a solid understanding of what your knowledge base’s purpose is.

Some knowledge bases seem to have a deceptively simple purpose, like "capture all of our internal policies and procedures in one place," or "provide support documentation for our SaaS product."

For this exercise, that is not enough. Instead, ask yourself: what problems is my knowledge base trying to solve?

This will help you prioritize the content you generate, as well as inform any number of style guidelines. It will also help you put a deluge of small requests in perspective.

Let’s say that you have an internal knowledge base with the purpose of capturing all of your organization’s internal policies and procedures in one place.

What problem does that solve?

Well, it’s probably solving a number of them:

• Lost productivity due to staff completing things incorrectly

• Lost productivity due to staff struggling to find the right person to contact to figure out how to do something

• Greater risk of security or compliance exposure due to staff not knowing correct policy/procedure

• General frustration and low morale at not having readily available tools to do our jobs

• Inconsistent implementation of policies or procedures across departments, shifts, regions, etc.

• General lack of transparency/consistent communication

• Siloed information

This list is important because it helps you set expectations with everyone you speak to about the knowledge base. Think back to my company strategy vs. conference room painting example above. Some people weren't offering opinions on company strategy because they didn't know enough about it to offer informed feedback. So having a list of clearly-defined and easy-to-articulate talking points about your knowledge base's purpose is helpful for getting more useful feedback from everyone.

It might help you make the case to your boss as to why this is needed--or make the case for having more than half of one full-time person’s time dedicated to it. It might help your boss make the case to the C-suite. And if you are the boss or C-suite, it will help you make better resource allocation decisions.

It can help you roll out the new knowledge base in a smooth way, allowing you to better anticipate where your users will have resistance or anxiety to the change. This, in turn, can help you identify ways that you can present it to your users that will make them more excited for it.

For handling massive feedback (particularly of the bike-shedding variety), having the problems-to-solve defined is important because it helps you:

1. Evaluate the request. A clearly-articulated list of problems becomes a great set of criteria to weigh all suggestions against, so you can make decisions and set priorities faster. Does this suggestion help me build the power plant? Does the solution so-and-so is proposing help me solve any of the problems my knowledge base needs to solve? Not only can you use this as internal evaluation (if it doesn't, it goes in a "nice to have/later" pile), but you can also explicitly ask this when you're not sure. In some cases, I have actually directed this question toward people offering me feedback, something like: Well, you know our goal with this is to solve xyz...can you make the case that your suggestion helps with that?

2. Put the request in context to others. When you have an articulated set of problems or mandates, you can say things like: "Thanks for your feedback; when we get to the bike shed, we’ll consider it. With this initial roll-out we are most concerned about solving xyz problems. We’re collecting all kinds of feedback for once we have those in-hand, and at that point we’ll review suggestions like this." This lets people know that you appreciate the feedback, you aren't ignoring it, but that it's not quite the kind of feedback that's most useful right now.

2. Be careful what you ask for (and be specific)

If you're getting this feedback after you've asked for input, then you might also be a bit at fault here. If you ask for feedback on your knowledge base, very often people will pick on small design flaws. They are like the bike shed, or the conference room paint color: people feel confident that they can offer an opinion on smaller details.

People who don't write documentation don't read like writers. Sometimes, that’s helpful for sanity-checking that you didn’t leave something out or use too formal language. But sometimes it means that you need to guide people toward the content-based critiques you need.

If you explicitly ask for feedback, be specific in what you’re looking for.

For example: "I just finished fleshing out the Subscriptions feature docs. Can you take a look and let me know what you think?" will probably get me pretty vague feedback.

Contrast that with: "I have a draft of the Subscription feature docs up. Pete, can you review the API documentation on [this page] and let me know if I've accurately described the endpoints, fields, and values? Marybeth, can you read through the 'what is' section and make sure I've described the feature in ways that make sense? Stephen, can you test following the steps in the 'configuring' section to be sure I didn’t miss anything? To all readers: there are a couple key configuration steps or points. I've used colored div call-outs here [insert screenshot example]. We don't currently have a set style for them. Do you think that brings enough attention to the information without being too obnoxious or distracting?" 

I've asked specific teams or SMEs for pointed subject matter expertise, and the one design question I've asked here is very specific.

This approach obviously requires you to take a little more time to structure your request, but it will help guide your feedback providers to give you things that are actionable and useful. 

3. Everything comes at a price

While none of us necessarily like to bring this up, if you start to get truly overloaded with small presentation requests, it’s worth noting that you can work on those--but at the expense of creating new content.

The key here is to avoid a "my time is more valuable than yours" or a defensive response. It's better to start with something a bit more tactful, like:

(me, looking at a huge list of requests): Well, you've given me a lot to think about. Out of all these suggestions [list if necessary], which would you say is most important?

(wait for answer; respond thoughtfully)

(If that answer was stylistic rather than content-based): I still need to write [insert list of content that you need to generate], and I'm trying to get content up to [list problems you are trying to solve], so I'd like to try to get drafts of the content available first and then revisit these design choices. Do you think the issues you've presented are preventing people from being able to [follow the documentation, etc.], or would I be okay waiting until I finished writing [content x] before I circle back to this?

This might seem flippant in my writing here, but it’s actually a very thoughtful conversation when you're on a team with limited resources: having an informed, transparent conversation about resources and priorities can help put in perspective what people are asking for. Styling your bullet list items a certain way becomes a "nice to have" in relation to things like getting docs written for setting up our software the first time.

4. Know your audience

In addition to considering the problems you're trying to solve (Tip #1), also consider your audience and how crucial design details are. There are some knowledge bases where design components are intrinsically important.

If this is the supporting documentation for your software or product, it helps guide people's interpretations of your product, and therefore needs to have as much care and attention put into its usability and layout as your product itself. But if that's the case, then a serious case for professional design help can be made: whatever your company invests in marketing, branding, or design for your primary product or service should also be applied to your knowledge base.

If, on the other hand, this is an internal tool that doesn’t need to match that kind of rigorous scrutiny (e.g. people don’t really get to choose another tool), having a well-thought-out information architecture will serve you far better than really fancy styling. Ease of use and utility end up being paramount.

5. Don't reinvent the wheel

In my experience, a lot of knowledge bases kind of fly under the official radar for things. Very often, there isn't a company culture that says documentation is important (or else you’d already have a tool for this!) and so sometimes this gets implemented initially as a stop-gap solution for a single team or department. Then, over time, as people start to use it, it expands. And then, suddenly, you start getting suggestions from people in decision-making positions telling you they'd like to see something done differently so that their team will have an easier time using it.

That's a very ground-up, organic adoption method. Don't fight it. It works well.

But if you start facing a lot of suggestions or requests for changes to look, feel, design, or branding that are outside your abilities as a content creator, it's time to ask: do we already have someone in the organization who does these things?

In many cases, you do. If this is an internal knowledge base, odds are good that you have a company website somewhere, or at least some marketing people who set brand requirements. If you are a software provider and this is your documentation, you undoubtedly have someone who--unofficially or officially--does design work. They may or may not have an explicit style guide, but they should at least have some internalized standards for it.

Ask around. Find out who that person/team is. Get them involved. Especially if you're not a designer by nature, being able to kick all of those requests to someone who specializes in it--and then just reviewing with them the suggestions they think are valid--can give you a lot more time to focus on your documentation. It will also ensure that your knowledge base is consistently styled and branded with the rest of your company's tools.

6. Choose style over substance

Regardless of the situation, though, user experience studies have shown this time and again: if documentation provides good content, people will stick with it even if it's visually bare bones. Believe it or not, people are quite willing to scroll through long pages of content as long as that content solves a problem for them (see the "Myths about Scrolling and Long Content Pages on the Desktop" section of Nielsen Norman Group's guidelines on using accordions to expand/collapse content, for example).

On the flip side, they won’t care how pretty it is if it lacks the content they need.

Think of your documentation a bit like food: no matter how pretty the presentation, if you don’t give people true sustenance, they won’t come back for more. Getting content generated and published is a far harder nut to crack than tweaking style.

7. Energy can neither be created nor destroyed

Underneath frustration or overwhelm, remember: this feedback indicates involvement. It means people are noticing and interested in what you're doing. The most ideal circumstance is that you not only get useful feedback for changes to make going forward, but you also get some more vested stakeholders in your knowledge base. More interest can often lead to more resources or outright involvement.

If, for example, you have a host of these small design changes you would love to make but you need to get through some content first, consider if the person asking you for the changes can help you get that content done faster. Do they work on a team that has a subject matter expert in this area? Are they, themselves, capable of making some of these changes? If you trust them, you may have just found yourself an additional knowledge base administrator.

Studies for bottom-up adoption of new software tools show that new tools often benefit from internal champions. If the person offering you feedback seems excited and enthusiastic, even if they aren't cut out for administrative tasks, you can still cultivate them as a champion. Harness that energy to work for you so it can continue to drive your knowledge base forward. Who knows--it might help shift the nature of conversations from conference room paint colors to company strategy!