Stop writing docs. Start helping!
(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.
- 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.
- 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