Skip to content

50 Docs tips in 50 days

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!

  1. When instructing a reader to make a new file or folder, acknowledge that one might already exist.

  2. When an instruction is conditional, put the condition before the action to perform.

  3. Repetition is a pedagogical tool to reinforce a concept, not a safety net..

  4. When you think (or realize) you’ll reference something frequently, make it a heading..

  5. Don’t let the easy fix distract you from the better edit.

  6. New gets old fast. Save it for timely or dated posts.

  7. Add file names as titles to your code blocks.

  8. You can’t remember (or forget) what you didn’t already know.

  9. Don’t make people figure out how one thing is “like” something else.

  10. Consider everywhere your headings will be used, not just in the body of the page.

  11. Alternative versions are more helpful than alternate histories.

  12. Let your docs tell their own story.

  13. Be aware of words that may have an unintended nuance.

  14. Make it clear whether your list is partial or complete.

  15. Don’t document workarounds. Fix them!

  16. You don’t know what your reader wants. Save effort (and words!) by not trying to guess.

  17. Group the most similar items together for a definition that flows.

  18. Use sequence words to help your reader progress through your instructions.

  19. When communicating updates to your project, emphasize what has changed for the reader.

  20. Make sure readers can actually add your “add this code” examples.

  21. Consider the surrounding context around your changes.

  22. Start with idea per sentence. Let it tell you whether it wants to be longer or shorter.

Toggle Comments

© 2021 - 2024 Sarah Rainsberger. Except where otherwise noted, and/or quoting external sources, the content of this site is licensed under CC BY-NC-SA 4.0