Tip 4 - make headings

Jun 27, 2024

Section headings help organize your content and make your text easier to both read and skim. When I have several paragraphs in a row without a section heading, I know I’ve likely written more than one “key idea.” That’s a good signal to look for where I might have moved on to a different idea that could be its own section.

But that’s not my only clue that I’m in need of a heading! Often, I’ll notice its time for a heading when I can see myself wanting to link directly to a paragraph. For example, in Astro, there are two ways to “add a renderer to a container” (using a helper function, and first importing then storing manually). Not only is it visually clearer to make a new section heading for each method, but separate sub-headings allow me to link to either method individually from other parts of the documentation.

Astro Docs contains many internal links so people can quickly access related content. This content might be expanded on in a guide, shown in an example in a recipe, or defined in an API reference. The closer you can get to linking the exact place in docs you’d like your reader to visit, the more helpful the link. Your reader doesn’t have to guess which part of a larger section is relevant to them.

Sometimes, I will discover after a page is already published that I wish I could link to a more targeted part of a section. Usually there’s a key idea that would really help provide extra context… and, I’ve already written it so I don’t need to say it again! But, it’s buried in a larger chunk of content and it shouldn’t be the reader’s job to find it.

Helping my readers navigate quickly and directly to the content they need is worth the rework. And, don’t worry if you didn’t predict the need ahead of time; when it’s necessary, you’ll know!

Toggle Comments