Tip 36 - not my problem

Jul 29, 2024

No docs site is an island! Astro docs overlaps with concepts from HTML, CSS, and JavaScript. Additionally, Astro can be connected to a CMS or backend service and deployed on a hosting platform. That’s potentially a lot of documentation our community needs that is outside of our own project!

Including other projects or services in your own documentation may be unavoidable. Who is responsible for publishing and maintaining “definitive guide to deploying Astro on Netlify” for example: Astro, or Netlify? (I know what my answer is…) In practice, the line may not always be easy to draw.

One PR suggestion I often make is to keep the focus on “working with” services and possible interactions between projects, not (re)documenting how they work. And absolutely avoid describing their UI at all costs! It is still possible to provide helpful guidance without providing too many details that are subject to change. Use language consistent with the other project’s documentation so your readers can cross-check or search in their documentation when they need further instruction.

✅ In your CMS dashboard, create a new post named test-post with the content type blogPost.
😐 Sign in to your CMS and click on your user profile to access your dashboard. Click the green + button the upper right corner to create a new post. Scroll down to the field for entering the content type and select blogPost from the drop-down menu.

When Astro’s code changes, I know about it. I monitor the appropriate repositories. I am directly notified to review accompanying docs changes, and I am even brought in to assist writing helpful CHANGELOG entries. When a feature, process, setting, or website UI changes at Netlify… I wouldn’t even know until my docs are already wrong and I am be at the mercy of a reader discoving and pointing it out.

“Docs are never done” and require continual (continuous? 😅) maintenance. Docs will occassionally be out of date. It may not always be my responsibility, but it’s my problem! To help keep up, I don’t take on any more responsibility than I need to.

See the whole list of tips!

Toggle Comments