If you’re a musical theater fan and involved in tech, you should absolutely check out <title of conf>! It’s a conference I conceived of with some of my friends which will showcase the musical and theatrical talents in our industry and teach tech concepts through performance. I named it for [title of show], a super meta musical about two guys writing a musical about two guys writing a musical… written by those same two guys.
Thinking about this show as often as I did growing up taught me a lot about creating impactful projects and putting them out into the world. When that project is a piece of software, one of the best ways to make sure it’s impactful is to write great documentation! Docs guide your users and can help prospective users decide whether your project is worth using.
The following are my suggestions for making your docs more user-friendly, all gleaned from my most recent listening of [title of show]!
Dial in your information architecture
“And now we yell in fortissimo!” - Untitled Opening Number
First up is the layout of information in your documentation. Is each topic arranged so that the relationships between them are clear? Have you written clear and descriptive headings? Does the reader understand what type of information they’ll find before they click a link on your site? You might have written the greatest tutorial in the galaxy, but it won’t do anyone any good if they can’t find it!
I recommend checking out Divio’s documentation system. It details how they break documentation into four categories: tutorials, how-to guides, reference guides, and explanation. These four functions of documentation address the various needs of your readers by presenting different types of information. If you separate your docs into these four categories and clarify the purpose of each, you can show readers to better navigate the docs.
This is perhaps easier if you’re writing from scratch. Totally overhauling an existing site takes care and time. If you don’t have the resources to do a full audit and major update, break the process down into smaller steps. Projects commonly have tutorials spread all over the place. Try starting the process by identifying any rogue tutorials and pulling them into one section.
You can learn more about the way Divio does documentation by watching Daniele Procida talk about "What nobody tells you about documentation".
Maximize usability and minimize shame
“You have a painting to paint!” - Die Vampire, Die!
It’s tempting to talk about how “easy” or “simple” your project is to use because… you want people to use it! It may even be true that most people who read your docs will agree with you. However, trivializing tasks that may not be so easy for some of your readers can leave them feeling discouraged. If things go wrong when someone is trying to “just” do something you’ve told them should be a breeze, the next question for a lot of people is “Well then what’s wrong with me?”
In many cases, you can cut this kind of wording out without changing the surrounding text. This is especially true of adverbs like “quickly” or “simply”. Remove them and the sentence will usually still make sense!
Avoid making too many assumptions
“I would know that confidence if I knew a way back to then.” - A Way Back to Then
Be on the lookout for language that assumes certain knowledge as well. Phrases like “you probably know” or “I’m sure you’re aware” can make people feel small. Even worse is writing docs without stating your assumptions at all! Struggling to make headway through a tutorial only to realize later that you lacked crucial context is an incredibly frustrating experience.
Beginning with a quick statement of your assumptions and any prerequisites for understanding the material can prevent your readers from falling victim to that frustration.
That said, the React docs don’t need to teach you everything about JavaScript even though you need some understanding of the language in order to use React (a JavaScript library which serves as the basis for many websites). When you feel the need to provide extensive background information on a given topic, consider linking out to other documentation rather than reinventing the wheel. For example, you could try referencing the Mozilla Developer Network web docs rather than going into depth about arrow functions.
Ask for feedback
“I wonder sometimes if she even likes me…” - What Kind of Girl Is She?
You’ve read this far and probably have some ideas about how you might apply this to your own project. Pause for a moment, though, and consider your actual users. What do they think? I can sit here and tell you what I think might make your docs better but it’s important to tailor that advice to the people who will actually read them!
Set up some kind of feedback system so that readers can communicate any issues they encounter. If possible, provide a method that allows them to give feedback on a specific page and include a form, link, button (whatever makes sense for you) on each page.
If your project is open source, you can ask folks to make the changes they want to see for you. Your docs can be an awesome entry point for new contributors! In general, and especially in this case, it’s super important to lay out a solid style guide to help maintain a consistent voice throughout your docs. Include any conventions around tone, spelling, formatting, and structure in your style guide and hold everyone who writes the docs to it!
Next steps
Check in with your docs! Which of these suggestions can you apply to make your own documentation more effective? If you’re looking for community around great documentation, grab a ticket to the next Write the Docs conference.
Bonus: if you’re into this whole tech topics as songs thing, check out this password safety PSA in the form of a sea shanty:
Rachel Tobac@racheltobac
To reach the ~youth~ we're going to have to make infosec sea shanties, aren't we? Guess so!
Behold the tale of kid who reuses their passwords & ends up pwn'd, then learns how to stay safe. We're on a mission to encourage unique passwords stored in a password manager with MFA on.00:15 AM - 22 Jan 2021
Top comments (0)