Tip 15 - don't doc when you can fix

Jul 8, 2024

This idea might be a little controversial, but at Astro docs, we always prefer to document things as they are intended to work. Docs continue to be the official source of (eventual) truth. If something is utterly and severely broken to the point your documentation doesn’t make sense, maybe that’s a sign that a recent update should be reverted, or perhaps should not have been released yet. This isn’t, as far as I’m concerned, a “docs problem.”

More commonly, there’s a bug, temporary constraint, or unexpected behavior that is going to be fixed. Our platform devs are generally responsive enough to prioritize a significant mismatch between docs and practice. We will collectively decide how big of a problem this is based on the feature affected, the number of people we think it affects, and the time needed to release a new version.

However, when a workaround will only be needed temporarily, I will not update the documentation for that feature. And, I may very well have a greater tolerance for “temporary” than you do. If I suspect create astro will be out of order for multiple weeks, then I might consider a banner or note in docs. Most other features? I take a different approach!

Directing your users to the appropriate place for issues, uptime status, and other non-expected behaviours is often more advantageous in the long run. Just like different docs pages are written for different purposes, your guides and reference material are not meant to be subject to the whims of an unnoticed failed test or upstream issue with a project dependency.

Train your readers to look in the right place for the information they need. This will help them learn where to go when they have problems that are not a result of incorrect docs, too.

And, I still want them to know “how Astro works” even if it’s temporarily not working! Yes, following your docs might not work at this exact moment, but when the workaround is removed… how will they know they no longer need this hack? Not only have they used (and maybe internalized?) a non-standard pattern, now you’ve given them a maintenance burden that they didn’t sign up for … a maintence burden that you have now signed up for, too, by the way.

If a problem is so severe and so far away from functioning that you are tempted to document it, that probably means that this is realistically how your project works anyway. 😅 And by all means, document “how your project works!”

See the whole list of tips!

Toggle Comments