50 Docs tips in 50 days

Jun 24, 2024

I realized while working on this site that it’s been a while since I’ve written for this site!

So, I’m hoping I can jump-start my writing by taking advantage of the delightful coincidence that I’ve got 50 days left until I’m 50 and motivate myself to write one, small, helpful or interesting tidbit per day.

(At least, I hope they are! They are things that help me while leading Astro’s community-driven documentation site.)

I’ll make a separate post for each one, and will share in a Fediverse thread on my Mastodon account but I’ll come back to this one and update the list as we go.

Let’s see if I can do it!

When instructing a reader to make a new file or folder, acknowledge that one might already exist.
When an instruction is conditional, put the condition before the action to perform.
Repetition is a pedagogical tool to reinforce a concept, not a safety net.
When you think (or realize) you’ll reference something frequently, make it a heading.
Don’t let the easy fix distract you from the better edit.
New gets old fast. Save it for timely or dated posts.
Add file names as titles to your code blocks.
You can’t remember (or forget) what you didn’t already know.
Don’t make people figure out how one thing is “like” something else.
Consider everywhere your headings will be used, not just in the body of the page.
Alternative versions are more helpful than alternate histories.
Let your docs tell their own story.
Be aware of words that may have an unintended nuance.
Make it clear whether your list is partial or complete.
Don’t document workarounds. Fix them!
You don’t know what your reader wants. Save effort (and words!) by not trying to guess.
Group the most similar items together for a definition that flows.
Use sequence words to help your reader progress through your instructions.
When communicating updates to your project, emphasize what has changed for the reader.
Make sure readers can actually add your “add this code” examples.
Consider the surrounding context around your changes.
Start with one idea per sentence. Let it tell you whether it wants to be longer or shorter.
Write the docs you have, not how you got them.
Front load prerequisites to avoid distracting side quests.
Your enthusiasm isn’t always contagious.
Use the words you mean.
Focus on your reader’s needs, not their mechanics.
Acknowledge the similarities to and differences from earlier instructions.
Use visual emphasis for conveying meaning, not intonation.
When your users have users, you may want or need to document for them, too.
Don’t explain what’s not in the example.
The better the name, the harder you have to work for the definition.
Start troubleshooting advice with the observable error, not what led to it.
Show the right thing so readers don’t internalize the wrong thing.
Links are going to be clicked! Use them strategically when you want readers to leave your page.
Don’t take responsibility for documenting someone else’s project.
You may need to “rearrange” to support your reader’s journey, not rewrite.
Save “but” for a truly unexpected turn of events. You can use “and” more than you think!
Don’t sound smart; make your reader feel smart!
“Make things happen” in your life, not in your docs writing.
Docs is not a conversation. Skip the pleasantries!
Assume that your reader knows whose docs they’re reading.
Sneak in “extra docs” with meaningful example file names.
Separate yourself from, and instead focus on, your reader.
Every new fact is “another thing,” but you don’t always need to call attention to it!
Emphasize the postive! Help your readers achieve, not avoid.
Document change like a verb, not just as a noun.
Use examples to enhance your point, not make it.
What doesn’t kill you makes (your docs) stronger.
Use tips for actionable, optional, been-there-done-that content.

Toggle Comments