The Barf-Librarian Technique

Internal documentation. There’s never enough, right? And getting it written is never enough of a priority, right?

How often have you asked a question like “what’s the process for submitting a bug report?” or “what tools do we use for web analytics?” and the answer has been “ask Jill - she’s been here for ages and she knows everything”?

It isn’t much of a leap to see why this is a problem. The moment Jill goes on holiday, your source of internal knowledge walks right out of the door. And you know the solution is to write more internal documentation, but Jill is so busy and no one else knows what to write, so the documentation never gets written.

Why internal documentation doesn’t get written

There are a number of factors that come together to stop internal documentation getting written. It’s rarely just one or two of these that cause the problem, but a whole suite of them together.

The tools you use for documentation are hard to use or stifle collaboration
There are processes in place that get in the way of moving fast
The people who have the knowledge and the people who want to write are different people
People are nervous about their ability to write in a compelling, narrative way or feel they don’t have time to write
People don’t know where the documentation should go
People don’t want to trample other people’s work even when they see a scope for improvement

The Barf-Librarian Technique

When I work with teams that are struggling to write and maintain internal documentation, I try to introduce a set of principles, which I have recently taken to calling the Barf-Librarian Technique (you can call it BLT if you like, but I like the full name).

This technique is about dividing the work of writing documentation into two separate activities, called… you guessed it… Barf and Librarian.

Barf

Most people with knowledge don’t want to be writing documentation. They want to be doing whatever it is they’re knowledgeable about!

It’s really common to find people who know a thing fretting about being asked to document it, because they aren’t confident with writing, they don’t have time, they don’t understand the processes, or some combination of the above.

The Barf phase of the technique is about not worrying about any of that. You have a bunch of knowledge building up inside you: your only priority is to get it out of you and onto the page, in whatever form it emerges. 🤮

Barf doesn’t look like coherent narrative with a beginning, a middle and an end. It’s not grammatically correct. It’s not pretty to look at. It might not make much sense to anyone but the person it emerged from.

But - crucially - Barf is visible to the rest of the team. Even if it is hard to navigate, it is documentation.

Librarian

Every team has people I like to call Librarians.

Librarians see something untidy, disorganised, missing structure or inward/onward links, or grammatically incorrect or incoherent, and they feel a strong desire to clean it up. 📚

If you’re not a Librarian, that’s OK, but I am confident that if your team is more than a handful of people in size, it will have Librarians present.

Librarians are usually quiet about their desire to improve messy documentation. Usually because of some combination of not wanting to tread on other people’s toes, not understanding the processes or the style conventions, or feeling that no one has asked them to do the work.

Freeing your Librarians and encouraging them to run wild in your documentation is how the Barf becomes beautiful, maintainable documentation.

Introducing the Barf-Librarian Technique in your workplace

For the Barf-Librarian Technique to be successful, a few things have to be true:

It must be very easy for people to make changes to other people’s work.
People have to be encouraged to edit other people’s work without asking for permission.
Your organization’s documentation structure and style guide must be open to change at a moment’s notice.
Barf must be prized. People should be celebrated and openly appreciated for dropping their unstructured, messy thoughts all over your beautiful tidy documentation repository.
People can Barf anywhere. There shouldn’t be a special “inbox” of unstructured content that then gets filed into the “proper place” by Librarians. All this does is create unnecessary process and a sort of “todo list” for the Librarians - before long it will be their only job instead of the one you’ve hired them to do.

Being a Librarian is a fun activity for people naturally inclined to do it, but it should happen naturally and organically as people encounter documentation that doesn’t make sense or could benefit from some order.

Nothing will kill the Librarian spirit faster than someone thinking it is their job to fix other people’s work, nor that there is some sort of “signoff process” for making changes. (If you have more than one Librarian on your team - lucky you! - they might get into “edit wars” over style/structure but don’t pre-emptively solve this problem because it rarely actually occurs.)

In order to make this work, you need to choose a technology that is suitable for the Technique. I’d say any technology is suitable if it has the following qualities:

All the documentation is in one place
Anyone can edit any page
A log is kept of the version history, so people can see what changes were made and by whom, and revert ones that were done in error

Word + Sharepoint (or Google Docs) is terrible for documentation productivity, because this model encourages too much access control, too much fragmentation of documentation, and too much formality in the content.

AI, too, is a bit of a false friend here. You can ask it to tidy up your grammar or format things to look more beautiful, but this is internal documentation and the things AI is good at really shouldn’t matter at all. The value of Librarians is their desire to tidy up and organise documentation and to connect with the team while they do it.

My personal favourite tool for the Barf-Librarian Technique is Confluence, but it’s just because I’ve used it more than any other. Anything that describes itself as a wiki will do. I hear Notion is great. I think some people even rate Microsoft Loop.

Choosing the right technology is the first step, but the only way this is going to work is with a cultural shift. It’s really critical that everyone feels they have permission to work on documentation at any time. That they’re not going to be told they’re wasting time or ruining someone else’s work. All documents must be owned by the whole team from the moment they are Barfed to the moment they win their first Pulitzer prize.

Let’s talk about your internal processes?

Need more Barf in your team? 🤮🤮🤮 Thought so! Let’s talk?

I am available for free 30-minute chats on any topic and I can’t wait to hear about your challenge and whether I might know someone who can help!

Fish Percolator is a technical leadership consultancy based in Yorkshire.

If your team is not running as smoothly as you'd like, you have long gaps between releases or bugs in production, or your people are not excited about coming to work every day... we can help!