Tis (still) the season of giving. So we’re giving away our Content Development Guide, our go-to document for our authors to reference when they’re creating content. Here’s the link so you can download the DITA files or the PDF: https://github.com/Jorsek/jorsek-cdg. Please take and use any parts that may be helpful to your organization’s needs.Hopefully, it can help you!The Content Development Guide ensures our authors write with and project a consistent company voice. It’s been an invaluable document for us as we continue to grow and assess our documentation needs.The Guide is a work in progress. We’re continually making changes and updates to it as our needs change.It’s also unique.
Typically, style guides, information models, and strategies are each standalone documents. Instead of having three large, laser-focused documents, we’ve invested some time into simplifying our Style Guide, Information Model, and Strategies to contain only what’s essential to Jorsek’s content needs.Then, we compiled those into a single document that guides and informs all our documentation: the Jorsek Content Development Guide. In the Content Development Guide, we’ve focused on the principles that underlie our style guidelines, information model, and strategies docs. Focusing on the principles and trimming the details made it possible for us to combine all three into a single, manageable document that acts as the central guide for all of our content development needs.Of course, our Content Development Guide includes some guidelines that are narrow and specific to Jorsek.
But because we shaved off as much inessential material as possible, we think the Content Development Guide is a good starting point for any organization that’s transitioning to structured authoring or is still in the early stages of implementation. The principles in our Content Development Guide can serve as the backbone for your structured content development needs.
The Benefit of the Guide
We’ve observed quite a few different types of customer needs around documentation and the creation and implementation of a content strategy. Some customers are transitioning to DITA from an unstructured environment. Some are just getting started in their content production. Some are both. And still, others are DITA and structured authoring experts. But all of them have in common the need for a content development guide, a substantive document to act as a unifier for an authoring team.For many of our customers, the first step in adopting structured authoring is to convert their existing content into DITA. Once they’ve cleared that hurdle, they often launch into writing and reusing chunks of content. Sometimes these organizations have well-formulated guidelines for how to reuse content, which writing style to use, and how they should structure their content.
Sometimes not. Either way, devoting time upfront to develop your organization’s information model, style guide, and DITA-use strategies will save you from common documentation mishaps that require labor-intensive effort to sort out. For example, having an established linking strategy can promote link-usage that’s consistent and easy to manage. Not establishing a linking strategy ahead of time can lead to authors using links in unmanageable ways. This leads to broken links and the painstaking task of resolving them.The same applies to writing styles. If there aren’t guidelines around grammar usage, the content that individual authors write will each take on the tone of voice of those individual authors.
This, in turn, results in an inconsistent company voice projected through your documentation. In many writing contexts this is fine. But technical documentation is about delivering content that aids the user with some task or operation or explains a concept to the user. Given the context of technical communication, an inconsistent tone of voice can lead to user-confusion and thus frustration for users reading your documentation.So, we hope our Content Development Guide can help your organization achieve its documentation goals. Enjoy it. And if you have any feedback, we’d love to hear from you. Note: In our next post, we’ll provide some strategies for implementing some of the principles in our Content Development Guide.
