On Writer's Side
Intelligent tools for writers and new ways to write better
The last Early Access release of 2024 – content reuse ♻️ and more fixes
Reusing content is one of the few things that software developers and technical writers are equally passionate about. Both know that avoiding duplication isn’t just a good practice, it’s essential – and it works for documentation, just as it does for code:
- Decreased redundancy: Reusing content eliminates the need to write the same information multiple times, saving time and costs for authors and editors.
- Reduced localization costs: Reusing content also means translators only need to work on unique text, lowering translation costs across all localized versions.
- Faster updates: Changes made to a reusable snippet propagate to all topics where it’s included, making your sources more maintainable and reducing the chance of errors or outdated information slipping in.
- Improved consistency: Reusing content ensures consistent terminology, tone, and style across documents – and consistency is the foundation of clarity.
- Reduced carbon footprint: Eliminating duplicates reduces the demand for storage space on servers as well as clearing your project from unused images and topics.
When should you start reusing content in technical documentation? The general advice is simple: as soon as you’ve outgrown your first README file. At that point, your content is likely getting more complex, more people are contributing to the docs, and the risk of inconsistencies, errors, and redundancy is increasing.
Reusing content requires effort to avoid certain perils and pitfalls, especially when you have a family of products built on the same platform, as is the case of JetBrains. Writerside actively develops features that make content reuse easier and more fail-safe.
Reusing content with Writerside
Any piece of content with an ID can be reused in Writerside – a content snippet, an entire topic, or even a hierarchy of topics from a table of contents.
- Topic level: Any topic can be included in multiple instances. Instances can be used to produce documentation for multiple products with shared functionality or different outputs for the same content (web or PDF), as well as to tailor product information for different audiences, or even to maintain separate versions of a documentation site.
- Table of contents level: You can include entire sections of a table of contents so that you don’t have to reproduce the same hierarchy of topics in multiple instances.
- Snippet level: You can reuse any chunk of content – a sentence fragment, an entire element such as a warning, or a larger block of text like a procedure, chapter, or table.
You can find more details in the docs.
New: Introducing libraries
Libraries are containers for reusable content snippets. You can have a single library with all your snippets, but multiple libraries might be more useful if your source base is large or if you have multiple content authors managing different product areas. In this EAP release, we’ve improved library management.
Now Writerside has a dedicated view where you can add the libraries you use most often and organize them in a hierarchy to group them by topic:
However, some core problems of content reuse still remain.
- Are there duplicates in my docs?
- Am I rewriting something that’s already been written?
- Will my changes to reused content break other parts of my source base?
- How can I create, find, and include text snippets more efficiently?
In the upcoming releases, we plan to tackle these challenges – hopefully, with your help!
Join our Slack community, subscribe to product updates, and share your ideas and experience about content reuse with us.
But wait, there’s more!
Reusable content and libraries aren’t the only things that kept us busy this past month. We’ve also listened to your feedback and fixed a handful of bugs and usability issues, such as making sure that the Save image dialog opens when you drag and drop an image into a topic, and more.
It’s been a big year full of development, both for Writerside and the industry. The pace of progress has been so high that we haven’t had a chance to appreciate what we’ve accomplished. We’re already looking ahead to next year, the next EAP, and the next set of challenges and opportunities waiting to be tackled.
We wish you all the best, and we’ll see you soon!
The Writerside team
Subscribe to Writerside Blog updates
