50 Docs tips in 50 days

Jun 24, 2024

Sarah

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.

Tags:

• docs
• 50 tips in 50 days

Tip 1 - "... if one does not already exist"

Developing Astro with Gitpod