Stop writing docs. Start helping!

Oct 5, 2023

Sarah

(approximate transcript below, in “speaker notes” formatting rather than properly written, with some slides sprinkled in and resources and references at the end)

I’m going to ask a question and we’ll get back to the answer a little later.

“Are your docs… good?”

Whether your current docs are…

• a README
• a few markdown files
• a Discord server
• a CHANGELOG
• the code itself
• an entire website
• … or nothing at all!

… they can always get better!

Not what you wanted to hear, right? This actually sounds pretty overwhelming… OR… is it a COMFORTING fact that “docs are never done”… so don’t expect them to be! You’ll never get there! You CAN’T get there.

You don’t have to WORRY about getting there.

With docs, you CANNOT, you must not, let “the perfect” be the enemy of:

• the good.
• the good enough.
• the #NWTWWHB. (Not worse than what we had before)

My name is Sarah, and I’m the docs lead at Astro.

I hope in just a few minutes’ time, you’ll see how achievable “better” docs are, even without:

• … a technical writer
• … a team of volunteers
• … writing experience
• … a lot of time

Whether you’re:

• … crafting your very first README

• … adding the changeset for your next PR

• … preparing a guide for using a new feature

• … starting to think about redesigning your entire documentation site (hint: Starlight!)

I’m going to make your docs better, I’m going to make YOU a better, more confident docs writer, without doing much WRITING at all!

Why do projects have documentation? Why do you have docs, if you do, for your project?

You might have said, “to document an API” or “to show how to use a feature” or “explain what the project is.”

I would argue, the sole purpose of documentation, the only reason it exists, is to be helpful.

• internal docs: help with cross-team collaboration and onboarding
• external docs: help people understand, evaluate and use your project
• open-source docs: help people contribute to your project

Documentation even helps you as you’re building, making design decisions, learning, and leaving yourself notes.

Documentation is… a source of truth, docs is support, docs is record-keeping, docs is even marketing, promotion and community building …

… but ultimately docs exist to help.

Remember when I asked at the beginning, “Are your docs ‘good’?” How did that make you feel? Was that an easy question to answer?

What if I ask instead, “Are your docs helpful“?

For many people, I think that second question feels different.

Changing the question you ask will immediately put you on the path to “better” docs… more helpful docs!

Notice that this ALSO changed the task of making docs from primarily a writing task to a helping task!

And, YOU ARE the foremost expert on your project, so you are the BEST person to help!

“Are your docs helpful?”

So how do we answer this question?

We begin to answer it by first understanding that it’s really a collection of questions, that start with the phrase:

Is this helping someone…

• get started with my project
• figure out what my project is or does?
• evaluate whether it’s right for their needs? (so you get the right users in the first place!)
• accomplish their OWN goals using MY project (e.g. add authentication to password protect some pages)
• troubleshoot something in their project that’s not working as expected
• use my project to the fullest
• avoid common pitfalls
• keep up with the latest changes in my project, so they can successfully update their project

Evaluating whether your docs are

• HELPFUL
• helpful TO SOMEONE
• helpful to someone FOR SOMETHING

… will get you further, faster, than any other single docs intervention.

Your docs can only be helpful to someone and that someone…

Helpful TO SomeONE WHO IS:

• Human
• (With needs/wants/desires/hopes/dreams)
• In a particular mood

WHO HAS:

• Context
• Goals/purpose
• Motivations, expectations

WITH A CERTAIN EXPERIENCE LEVEL WITH:

• Code
• The industry
• Your project

WITH VARYING

• Language proficiencies
• Bad experiences (“burned before”)
• Pre- or (mis) conceptions

AND ONLY LIMITED

• Attention
• Patience
• Time
• Energy
• Resources (internet speed/cap, hardware)

They also need to help someone do something:

• Learn
• Conceptualize
• Evaluate
• Achieve
• Build
• Fix
• Test
• Upgrade
• Improve
• Experiment
• Convince (themselves, someone else)
• Solve a business problem or technical challlenge

But, docs should ultimately be helpful at getting people OUT of docs, and back into (using) your project.

Now, let’s look at some characteristics of helpful documentation:

CLEAR AND CORRECT

If your docs are wrong, they are not helpful.

If docs are factually wrong, if they’re misleading, if they’re outdated, if they’re technically correct but so confusing you’d never know it… they are not correct. They are WRONG.

You might even have some existing documentation that … isn’t really helping anyone do anything! Instead, it’s more words on the screen making it harder to see the helpful content!

Action Items:

• Read every statement in your docs for ACCURACY
• Or, if you’re starting fresh, ONLY WRITE TRUE STATEMENTS
• Go through each part of your docs and identify WHO this helps, and WHAT it helps them do
• Less is more: both in content AND in style!
• Use clear, simple language: No one ever complained, “Gee, these docs are just too easy to read!”

If you’re not sure whether something in your docs is entirely clear and correct, and you can’t immediately see how to make it better… REMOVE IT:

“No documentation means I go look somewhere else for information. Incorrect documentation means I waste my time.” - Mason Egger

Incorrect docs reduce credibility. They can make people frustrated enough to stop using your project and choose another.

If your users can’t be successful, then they do NOT use your project; they DON’T spread word of mouth (at least, not the good kind), they don’t create items themselves that showcase your project. And they don’t contribute back and improve your project.

If it’s not clear, and correct… delete it! I am giving you permission! It wasn’t helping you anyway! It was frustrating people trying to use your project and potentially generating ill will and bad vibes!

If you’re worried you might have deleted something important, it’s fine. It’s the internet! Someone will tell you.

CHECK IN: Congratulations! You’ve made your docs better and you haven’t written a single thing!

We’re going to take things one step further and make your docs even more helpful:

Navigable and Discoverable

• Can people move around your documentation and find what they need?

• Are things where people expect to look? If they first look in the wrong spot, can they easily GET to the right spot?

These concepts relate to Information Architecture, and you can get into things like “signposts”, “escape hatches/off ramps”. These are all the structural things we add to our documentation to help people quickly and easily situate themselves and move around.

When someone lands in your your docs, can they get where they need to go before they lose hope? And remember that a lot of people will enter your documentation via a web search, and not necessarily ”on page one.” So every page you have needs to pull their own weight. This is not just a task for a landing page.

The good news though, if there’s only one page, your reader can’t be on the wrong page.

I’m serious! If you don’t know how to structure your content, there is nothing wrong with one huge README to start! Even if your readers have to look around, at least they’ll know they’re on the right page!

If the only reason docs exist is to be HELPFUL, to SOMEONE, trying to DO SOMETHING, then the first step in organizing your content is thinking about how to get your readers to the material that actually helps them accomplish the task they came for. e.g.:

• If they are coming to quickly look up a reference value, like a property name or config option, make sure they don’t get stuck in an onboarding tutorial!
• If they want to learn about what needs your project solves so they can decide whether to use it, don’t make them get stuck in implementation details before they even know what it is or does!

Here’s where a framework like Diataxis can be helpful: by identifying parts of your documentation by content type and reader goal, you can logically group sections of your docs and start to provide a helpful structure.

But the key thing is, if someone is not reading your docs like a book, top-to-bottom, first-page to last-page, do you have a plan for how will they discover and navigate to the clear, correct information they need?

Action item:

• go to literally any random point in your documentation, and imagine you are a reader who is not in the right place to get the info you need for a particular goal. Think about how your docs could direct them there, quickly and accurately.
• Is this solved by a TOC? a search widget? a “How to read these docs” page? an internal link?
• If you have multiple pages or files, do the titles accurately represent the content? Does your content live under the title you’d expect?

So, at this point, I’ve now basically said: Don’t lie (and, delete any lies), and don’t hide stuff (if you have to, throw everything on a single page. Good news, CTRL+F works for everyone!).

This is, I think, STILL an achievable bar for docs that help your readers without any new writing!

If every statement in your docs is true, and people can find, read and understand what they mean… Congratulations! You have Minimum Viable Docs! (whispers If you have to, you can stop now)

But, of course, there are characteristics of well-written docs, and there are also some pretty common anti-patterns.

There’s no shortage of talks on “how to write good documenation” that go into specifics, and I DO recommend you check out some great ones if you want to get better at writing! But that can get overwhelming and we already know that WRITING is secondary to HELPING.

• It might feel like there’s a scary Docs Police waiting to criticize you and that there are a lot of potential failure pitfalls.
• Instead of thinking of these as things to worry about getting wrong, think of them as things that you DON’T have to worry about; things NOT TO DO because they are NOT YOUR JOB as a helper.
• These things “thou shalt not do” actually REMOVE pressure and responsibility, and are guard rails to keep you focused on a productive path towards helping.

So, I absolutely love this social media post, because it perfectly demonstrates everything we’ve been talking about here.

It’s CLEAR, and CORRECT. If you’re looking for the command to install Bun, these are the words you will search for! It introduces exactly what’s coming next, and it’s not hidden in a bunch of other words.

This edit is NOT me saying, “BAD AUTHOR, BAD DOCS!”

This edit is me freeing the pull request submitter from the responsibility to:

• write something clever
• motivate the reader
• get all the punctuation correct in longer, multi-clause sentences
• have 10 times as many words to proofread and spellcheck

My edit reminds you to focus on “helping” instead of “writing.”

Similarly, many other “Docs Don’ts” are actually “don’t worry abouts!”

If less is more, then here are some things you can remove or stop doing that reduce clutter and confusion in your docs.

1. Don’t use “we”, because you’re not sitting there with your potentially frustrated reader
   • This frees you from the extra work of checking that all your we/us/our/let’s all agree. You know what’s super easy to check? You and your.
   • Using “you” also naturally puts the emphasis on your reader, and what they are doing. It guides you to thinking about helping THEM. (What might THEIR set up look like? instead of writing “our” which can trick you into thinking about your OWN context or situation that your reader might not share.)
   • Often, these instructions work without any “you” at all, and become even clearer.

2. Don’t use “should” - Should implies uncertainty, and your readers are looking to YOU for what to do. If your reader really MUST do something, just say that.
   • Again, sounds like a rule we just made up! But I guarantee you that we are freeing you from feedback from a confused reader!
   • “You should create a new folder for your blog posts.” Do I… have to do this? What happens if I don’t, and how bad is that? What else could I do?
   • Not only do your sentences get clearer, but your reader stays laser-focused on the task at hand without any doubt. -> Create a new folder for your blog posts.
   • I am giving you permission to avoid writing, and just tell someone directly what to do! Even when more things are possible, if you WANT them to do this to have a successful outcome, just say it that way. THIS FREES YOU from the responsibility of describing every possible path when you, the expert in your own project, already have a recommendation and know the happy path. You can help. Don’t write. Just help.

ACTION ITEMS:

• Don’t stress out about writing rules, but embrace them as telling you things that aren’t your responsibility!
• Pick one or two (I suggest “we” and “should”), or just read through your docs looking for things that aren’t your responsibility, and remove them!

In conclusion, think of yourself as a HELPER. Someone who just happens to be helping in writing.

• helpers don’t need to entertain or write beautiful stories
• they need to make CLEAR, CORRECT information available. Ideally in such a way that readers can DISCOVER, and NAVIGATE it. (CTRL+F is your friend!)

And The best help is CONTEXTUAL: it is FOR someone who is trying to DO something specific.

• this person may also not be in the greatest state to RECIEVE help, but they are in your docs because they need it.
• don’t overwhelm. Less is always more.
• You can probably improve your docs RIGHT NOW by deleting, not writing more!
  • delete words like “should”; delete outdated or unmaintained docs, even if you can’t yet replace them; delete entire pages if you are afraid people won’t find them, and put everything on one page if you need to!

You can have great docs even if you aren’t a great writer. Because in many cases, maybe even most of the time, the less you write, the more you help.

References and Resources

• Diataxis
• Talk - Mason Egger: Write Docs Devs Love: Ten Tips To Level Up Your Tech Writing
• Talk - Ashley Bischoff: “1Up Your Writing with Plain Language” at Fronteers Conference 2017
• Book - Docs for Developers
• Book - Write Useful Books
• Book - Every Page is Page One
• Audio - Making Documentation Developers Love

Tags:

• docs
• open source

Developing Astro with Gitpod

The value of non-code contributions to open source