This was presented at Code4libBC 2024. It’s a version of my previous Support Driven talk, edited down and for a library audience.
Slides
Introduction
Hi Everyone, thanks for joining. My name is Cynthia Ng, although most people know me and you’ll find me online as Arty.
As a quick note, I have a lot of links in the presentation for reference and examples. I’ll be making the slides available, so you’ll be able to get them afterwards.
About me
I want to start with a little bit of context about myself. I’ll not bore you with a long bio, but for the context of this presentation, there are a few things I want to mention.
Everywhere I’ve worked, I advocated for good documentation. When I can’t make that documentation public, I’ve often blogged about the parts of my work that I could. I did it for many reasons, though primarily to record what work I had done, and to “pay it forward” by sharing my knowledge with others.
I used to do a bunch of web development work, which included doing information architecture reviews, and reviews of internal documentation tooling.
I’m also currently the “owner” (primary maintainer) of my work (GitLab) organization’s handbook.
Last but not least, I like cute animals, and have to have at least one in every presentation.
A handbook
Before we get into it, some questions to start
- Do you have processes that need to be followed?
- Do you have shared workflows with other teams?
- Do you have information that you frequently share?
- Do you have people from other organizations ask how you do things?
These are of course very general questions, but hopefully they get you thinking.
What is a handbook
To make sure we’re on the “same page”, let’s define what we mean by handbook.
Wikipedia says:
“A handbook is a type of reference work, or other collection of instructions, that is intended to provide ready reference.”
Which is fairly general.
At GitLab, we define it using different words, but has the same basic idea:
“The handbook is the central repository for how we run the company.”
Honestly, to me that sounds like it could be almost any information that people need to refer to.
And at your organization, you likely don’t call it a handbook. Maybe you call it a wiki, or an intranet, or it might just be a set of shared documents that has the kind of information we’re talking about. Though, for the purposes of this presentation, we’ll keep using the term handbook, think about whatever you’re using to store any information on how your organization is run.
Why a handbook
If you can put anything in a handbook, why would you do it? What purpose would it serve?
Probably the most common reason is to have what we call a “shared reality”, where all team members have the same defined objectives and consume the same information to bring those objectives to reality. To store and maintain that shared information, you need a “single source of truth” (SSoT). Depending on the type of information and its permanence, that’s not always going to be a handbook, but you should consider it the default.
Often when writing in long form, because we’re not sure who might end up reading it, we’re more likely to write with lower context.
“Low-context communication assumes that the person you’re communicating with has little or no context about the topic at hand.” – TeamOps
The lower context information allows for greater understanding for anyone who doesn’t already have in-depth knowledge of a particular topic, whether that’s a new team member, a team member who has never worked on the specific topic, or someone outside of the team.
Building on these, documented workflows enable a lot of other benefits.
Creating a handbook
As information professionals, I imagine you don’t need much convincing that writing things down is important.
While I understand options may be limited where you are, and you likely already have somewhere you’re storing such information, I want to quickly cover some of the considerations that might help either create a handbook, or increase its usage.
What you need
There are a few basic things that you need:
- Buy-in: You can start with your own team, though ideally, as many people in your organization as possible.
- Location / Version controlled tool: Obviously, you need to decide on what tool you’re going to use and where it will live. You want an easy to find place, and preferably use something your organization already has so it’s easier to expand. Ideally, whatever you use is version controlled, so it’s simple to compare and see changes: the author, the date/time, and the reason. The specific tooling doesn’t necessarily matter.
- Easy (enough) to use
- Reinforcement: Putting things in a handbook needs to become a habit. For it to become a habit, you’ll need to reinforce the action.
- Public by default (separate internal only): If at all possible, start and keep things public. Obviously, some things need to be kept internal, so you’ll also want to consider how to do that. Ideally, whatever tool you use allows for specific pages to be made private.
- Start small and iterate: Last but not least: start small and iterate. If you’re making a new handbook, just start jotting things down. If you’re moving content, you can move one page or section at a time as you use it, and consider it an opportunity to review whether the content is up to date.
[Slide] Documenting everything isn’t exactly easy, so it takes time to create and grow a handbook. It doesn’t start completed, and really, it’s never done.
Set expectations to encourage contributions
To grow a handbook, you want to set clear expectations to encourage contributions.
- Invite collaboration on changes. Aside from version control, ideally the tool you use has a way for people to suggest changes and provide feedback before it makes it into the handbook. Especially if the tool doesn’t allow for that, you want to have some documented way for others to provide feedback.
- Have guidelines on what level of review is required: Related to that, one recommendation is to have guidelines on when a review is required. Fixing a typo shouldn’t need review. More substantial changes might need a manager, or the maintainer of a page.
- Have clear guidelines on what should be internal-only information, and how that should be stored.
- Doesn’t need to be perfect: While it may be public, the true audience of the handbook is still the organization itself. The focus is to make sure other team members understand it, so it doesn’t need to be perfect, and we can always improve it with further edits, since things are not “set in stone”.
Why a public handbook
Okay, so it’s not unusual for our organizations to have a handbook, or something similar. The real question is why do we need a public one?
The reasons you would have a public handbook actually apply to why you would have an internal one as well, but I pulled out a few points that I believe are more salient to making it public.
Efficiency
I already mentioned efficiency, but remember at the beginning how I asked you whether you’ve ever had to frequently share something? Or if others ask you about how you do something at your organization?
We often want to share with other organizations, and having a public handbook is a great way to do that.
Take this example from a Slack workspace that I’m in where someone asked about creating a liaison role between support and product:
Mariana: Hey all! Any recommendations or best tips on how to create a role as a liaison between Support and Product? This would be someone on the Support team who meets with a product lead or manager to discuss any upcoming changes to our product, prepare support documentation to reflect these changes, and be the voice of the customer
[…]
Arty-chan: I’m not sure how much reading you want, but here’s the description on what we expect support team members that are product counterparts to do: https://about.gitlab.com/handbook/support/support-stable-counterparts.html
There is so much information and nuance to building a relationship with another department, but I could link to our public handbook page and let Mariana know to ask any follow up questions she might have. Being able to link to a page saved me a ton of time, and lets her decide how much or little information she wants to take from it.
Consistency
While a handbook provides consistency for the team, making things public means that you can literally be on the same page as people outside of your organization as well.
Collaboration
Naturally, collaboration improves within the team and your organization when you have things written down, but it can improve from public input as well. Using the previous example, if Mariana noticed any issues, even something as simple as a typo, she could submit suggested changes.
Operational transparency
If you can expose a list of changes, you can show how your organization is constantly improving.
Continuing on our example, if Mariana had any follow up questions, I could look at adding the answers to the handbook page to improve it and answer those questions for anyone else in the future that might have them.
In an article on Operational Transparency for the Harvard Business Review, Ryan Buell found that “when people see the work going on behind the scenes, they value the service more.”
This type of transparency can also be beneficial when interacting with your users.
Community resource
Most of all, having a public handbook can be a great way to give to the community. A number of organizations have a handbook, but it’s not common for them to be public.
[Slide] I’ve had people tell me how they’ve found a public handbook helpful. And while you won’t always know about it, anything you’ve made public can and will often assist others, especially those who have limited resources.
I remember when I started digging into cataloguing rules years ago, there were very limited resources online, and I was immensely grateful to a small US county public library who had published their cataloguing guidelines on a public wiki.
By the way, if you know of any public library “handbooks”, please let me know.
Data source
Having the handbook public means that it becomes easy to search for those inside and outside your organization. It also becomes a data source for AI. While they’re not great right now at answering a lot of questions, the more information a model gets, the more accurate it becomes. There are whole articles on how best to format content for ingestion, so I won’t go into it here.
Take away
I know that was fairly general, so I’m happy to answer any questions about any specific aspect you’re interested in, or point you to a handbook page that already answers it!
It’s normal to think about the internal benefits, but I’ve been amazed to see how
A public handbook [can be] a way to give back
to the community and profession.
Even if your organization isn’t willing to make your handbook fully public, there are other ways you could make your work transparent, such as through writing blog posts, articles, newsletters, etc. Or you might upload resources to something like the library toolshed, though I know that’s not as active as it used to be.
It’s all about doing what you can and taking a step forward.
Thank you
Thanks for reading to the end!
Learning (Lib)Tech 