Tip 6 - new gets old fast
Astro releases new features all the time. We let our community know about them through several content channels: our blog, social media, and the project CHANGELOG in the code repository.
All of these are announcements that are meant to exist in the moment and to draw people’s attention to something new. Documentation of the feature, however, has a different purpose, and a different lifespan.
One PR suggestion I often make is to remove text describing a feature as “new” in its official documentation. “New” features age quickly, so save yourself the extra maintenance burden of deciding when they are “no longer new” and going back to update your docs when they are “old”.
Knowing that a feature is “new” may not even be particularly helpful to a reader who has never used your project before, or who is several versions behind. Instead, consider labeling features with the version of the software in which they were added. This is not only more precise than “new”, but also future-proof because it does not need updating.
If you’d like your docs to highlight newly added content, consider ways to automate adding and removing this content. For example, Astro Docs uses conditional logic to automatically display a small “new” badge only if a feature was added in the latest stable version.
While “new” features of your project may be exciting for you, your documentation exists to serve the needs of your readers. They may just be getting started and everything is “new” to them!
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 
