.avif)
Getting a team of technical writers to produce consistent content can feel like an impossible task. Without a shared set of rules, you get variations in voice, style, and structure that confuse users and erode trust in your product. A Content Development Guide (CDG) is the foundational document that solves this problem. It’s your single source of truth for how content should be written and organized. In this post, we’re pulling back the curtain on our own internal processes. We’ll walk you through the three core pillars of our CDG—Style, Information Model, and Strategy—that we use to create all Heretto documentation. Think of it as a practical blueprint you can adapt for your own team to build a scalable, consistent, and effective content operation.
Writing with Clarity: Our Style Guide Principles
Disclaimer - I don’t intend my discussion of our Style Guide, Information Model, and Strategies docs or the CDG itself to take the place of a well-formulated information architecture that’s specific to your organization. I am providing what I think are helpful guidelines and principles to consider when building your own information architecture, often with the help of a consultant. Here’s a link to a post about when hiring an information architecture consultant would be in your best interest. When Do You Need a Consultant?
The Heretto Style Guide contains guidelines for writing and grammatically styling Heretto's content, specifically for things like abbreviations, file names, capitalization, and punctuation. To adapt our Style Guide for your organization, you can use some of the existing topics as-is or modify them to align with your organization’s guidelines for each topic. You’ll likely want to add additional topics to address other styling concerns that are specific to your industry or organization.
Two examples immediately come to mind. At Heretto, we strive to write in active, second person voice in all our content. However, you may be working in an industry that’s heavily connected to scientific research. Often it’s the case in those fields that writing in passive, third person voice more effectively conveys the content. If you want to emphasize a specific effect that follows some cause, and the cause isn’t important, then using passive voice may be more effective and practical. Sometimes the content is just easier to consume if you don’t tell the reader who’s doing the action because the actor isn’t important. If that’s the case for you, you’ll want to cut out or at least heavily alter our Style Guide’s Voice topic. Another example of a way to adapt our Style Guide is our Diction and Punctuation topics. We’re a software company. So we’ve laid out a few diction guidelines that are specific to the software industry and Heretto in particular. If you’re in a different industry, just replace our jargon with your jargon. Similarly, our very short Punctuation topic states that Heretto follows The Chicago Manual of Style. But perhaps APA is the standard for your industry. If so, change the Punctuation topic to reflect that and make the appropriate alterations to the related topics.
For more information on citation and grammar methodologies, see https://owl.english.purdue.edu/.
Structuring Content for Success: The Heretto Information Model
The Heretto Information Model contains guidelines for how we structure our DITA content. This includes instructions for which information types to use, how to use some elements in a topic, and how we structure maps. Our Information Model isn’t exhaustive, and some of the guidelines are specific to our output, which is our built-in-house delivery portal. [link to the docs site]. Not being exhaustive is intentional. There are DITA elements that our writers occasionally use that we don’t mention in the Information Model. We don’t want our Guide to be overly restrictive. It’s a guide, not a rulebook. And provided our writers are operating within the guidelines set out in the Guide, we want them to have the freedom to generate creative content, which includes occasionally using some less common elements. Giving our writers the freedom to explore DITA’s available elements helps our team to come up with creative DITA content models. That freedom won’t work for a lot of organizations. Some technical writing teams have strict requirements for their content.
Some have their information types specialized to include certain elements while restricting others. In those kinds of cases, incorporating the freedom our Guide allows would negatively affect those teams. Of course, those kinds of teams typically have their writing guidelines and rules already in place. They should ignore the recommendations and structures in our Guide! But if you’re just building your information model, you can use the Heretto Information Model as a checklist of elements and structures that your organization may choose to use.
For example, we only use the default DITA topic types for our documentation. Again, that’s intentional. We’re the makers of a DITA CCMS, and so we want our topic types to have the full range of DITA elements available to test and use. Most of our customers have custom templates with restricted sets of elements, and these are specific to their needs as laid out in their own information architectures. So, take some of the guidelines we mention in our Information Model and scrap the unnecessary ones. Here’s a real example of how to adjust our Information Model. At the time we made our Content Development Guide available, the structure we used for our maps started with this:
- <map>
- <title> </title>
- <topichead>
- <topicmeta> <navtitle> </navtitle>
- </topicmeta>
- </topichead>
- <topicref>
- </topicref>
- …
- </map>
We’ve since restructured our maps, to begin with, a <topicref> instead of <topichead>, which looks like this.
- <map>
- <title> </title>
- <topicref> </topicref>
- <mapref>
- <topicref> </topicref>
- ...
- </mapref>
- ...
- </map>
Each map begins with a <topicref>, often followed by other <mapref> elements, which in turn all begin with a <topicref> element. Our current output specifications drove us to this decision. We could still use the structure, and we may move back to it at some point. For the time being, however, we want a particular behavior and user experience on our documentation site. So we switched structures to get the behavior we want, and our updated Information Model reflects that (on our documentation site, not the downloadable docs linked to above). If you’re just building your information model, try out the model we suggest in the CDG. If you don’t get the results you want, switch things up. Hopefully, the CDG at least gives you a place to start building out your full information model.We encourage you to take the upfront time to think through your own information model and make strategic decisions. Taking the upfront time will pay off later in consistency and efficiency in content production.
The Core: Heretto CCMS
At the heart of any robust content strategy is a system that can handle the complexity of creating, managing, and publishing technical documentation. This is where a Component Content Management System (CCMS) comes in. Think of the Heretto CCMS as the central nervous system for your content operations. It’s designed specifically for the demands of structured content, providing a single source of truth that eliminates information silos and streamlines workflows. Instead of juggling disparate documents and platforms, your team can work within a unified environment built for collaboration and efficiency, ensuring that every piece of content is consistent, accurate, and ready for delivery to any channel your audience uses.
Content Reuse and Version Control
Two of the most powerful features within the CCMS are content reuse and version control. Content reuse allows you to write a piece of information once—like a safety warning or a product description—and use it in multiple documents. When you need to update that information, you change it in one place, and the system automatically updates it everywhere it appears. This not only saves an incredible amount of time but also drastically reduces the risk of inconsistent or outdated information reaching your customers. Paired with this is robust version control, which tracks every change made to your content. This creates a clear audit trail, allows you to revert to previous versions if needed, and ensures your team is always working on the correct iteration, preventing accidental overwrites and lost work.
AI-Assisted Authoring with Etto, the Heretto Copilot
Writing technical content requires precision and consistency, but it can also involve repetitive, time-consuming tasks. This is where Etto, the Heretto Copilot, steps in as your AI-powered assistant. Built directly into the Heretto CCMS, Etto is designed to work alongside your writers, not replace them. It handles the heavy lifting on tasks like summarizing complex topics, generating initial drafts of structured content, or rephrasing text to improve readability. This frees up your team to focus on the high-value work of creating clear, accurate, and impactful documentation. Etto acts as a built-in quality check, helping maintain consistency across all your content by suggesting improvements and ensuring adherence to your style guidelines.
Putting Our Principles into Practice
Heretto Strategies contains guidelines around linking, reuse, versioning, etc. The Strategies are the culmination of countless hours of discussion about our content development objectives and long-term goals. The Strategies guidelines are perhaps the most important component in the full CDG. They underlie and inform our Information Model. They provide the structural framework for our content, everything from the folder structure we use in our Content Library to our particular release notes strategy. In some ways, our Strategies are directly part of our broader information architecture, and in some ways, they are more foundational. While our Strategies don’t contain any models for how to structure our DITA content, they guide our writers in how to organize and manage all content they create. Organizationally, then, they are part of our information model or architecture. One of the more controversial parts of our Strategies has to do with thinking about our writing with a “map-centric” mindset. We understand “map-centric” in two related but distinct ways. First, though our team writes with reuse in mind, reuse isn’t our end all be all. Yes, of course, we want to be able to reuse topics. But it’s also very important that our content is engaging and that much of it has a readable flow. Writing keeping both reuse and flow in mind is difficult. Sometimes we have to prioritize reuse over the flow. Sometimes, the opposite.
But each topic our team creates is part of a larger deliverable. For our documentation, we’ve found that the ability to reuse topics is slightly less important than our ability to create larger deliverables that provide a nice, readable flow. One reason is that we produce lots of content that’s not task-oriented. No matter what we’re writing, though, our goal is to maintain both reuse and flow.Writing documentation with the mindset that, roughly, “every page is the first page” a user may encounter means in our technical documentation that the first time we use a term, such as ‘Content Development Guide,’ we always include the full name plus a parenthetical with the acronym ‘CDG.’ Any later usage in the topic, we use only ‘CDG’ when referencing the Content Development Guide.
This methodology can lead to some repetitive language if you read the document from start to finish, which includes more than one topic that references the CDG. That is, sometimes the “every page is the first-page” approach negatively affects the flow of the larger deliverable. Again, we try to strike a balance between the ability to reuse content and with the flow of a document. But there’s always give and take. Depending on the type of content you’re creating, there may be cases in which you need to disregard the notion that each topic needs to stand alone or be the first page. You may need to write individual topics thinking about them in the content of their larger deliverable.
The type of deliverable you’re creating should dictate how you approach your writing. Keep in mind that we intended our Content Development Guide for web delivery, specifically thinking that a user may encounter any topic first. Reading it cover to cover would be cumbersome and unnecessary. Just because our Guide implies that we often write that way doesn’t mean you should. Scrap the guidelines implying that you should write with the “every page is the first-page” approach if you’re building a deliverable that’s meant to be read cover to cover. In fact, don’t follow our Guide in that regard if your output documents aren’t meant to be topic-based deliverables.Second, having a map-centric mindset also means that our writers don’t create topics that won’t immediately be put into the context of a map. Having all of our topics in a map from the beginning gives our writers the flexibility to version the content more easily, and gives us the ability to see how key definitions will resolve and thus an idea about the output for a particular deliverable. Whatever particular strategies you incorporate into your content creation, we recommend taking the time to formalize your own Strategies as part of your larger information architecture. Investing the time to formalize them will ease the management efforts you need to exert through your content production cycles.
Delivering Content Everywhere with the Deploy API
All the strategy and structure you build into your content pays off when it’s time to publish. This is where your hard work meets the real world. Getting your content in front of users shouldn't be a manual, channel-by-channel process. Our Deploy API simplifies this by letting you publish content to multiple destinations—like websites, customer portals, and PDFs—with a single action. This ensures that no matter where your audience finds your information, it’s consistent and up-to-date. It’s the practical application of a map-centric mindset, allowing you to manage a single source of truth that powers every user touchpoint without extra effort.
Creating a Self-Service Hub with Heretto Portal
One of the most powerful destinations for your content is a dedicated self-service hub. The Heretto Portal is designed for this exact purpose, turning your structured documentation into a centralized, searchable knowledge base for your users. This is where the "every page is the first page" approach truly shines, as users can land anywhere in your documentation and find the answers they need. By providing a single, reliable place for information—from getting-started guides to detailed API documentation—you empower users to solve their own problems, which builds confidence in your product and reduces the load on your support teams.
Customizable and Search-Optimized
A self-service hub should feel like a natural extension of your brand, not a generic third-party site. The Heretto Portal is fully customizable, allowing you to align the look and feel with your company’s branding for a seamless user experience. More importantly, it’s built with search at its core. The structured nature of your DITA content makes it highly discoverable, so users can quickly find relevant information with a simple search query. This turns your documentation from a static library into a dynamic resource that actively helps users succeed.
Handling API Documentation with Precision
A solid content development guide isn't just for user manuals and knowledge base articles. It’s also critical for one of the most important assets for any software company: API documentation. Developers rely on this content to integrate with your products, and a poor experience can send them looking for other solutions. Applying the same principles of structure, style, and strategy to your API docs ensures they are clear, consistent, and genuinely useful. This means thinking about how they fit into your overall product information ecosystem, not treating them as a separate, isolated project. When you treat API docs with the same care as your user-facing content, you create a more cohesive and professional experience for everyone who interacts with your product.
Unifying Product and API Documentation
One of the most effective strategies for API documentation is to stop treating it as a standalone resource. Developers often need to understand the broader product context to use an API effectively. When you house your product and API information in one place, you create a single source of truth that serves multiple audiences. This unified approach breaks down information silos and ensures consistency in terminology, branding, and style. For example, a platform like Heretto allows you to publish secure, interactive API documentation directly alongside your other product guides in a centralized portal. This creates a seamless experience where a developer can easily switch between a conceptual product overview and the technical specifics of an API endpoint without ever leaving the documentation site.
Authored vs. Generated Documentation
Your API documentation strategy will likely involve two distinct types of content: authored and generated. Authored documentation is the human-written content—the tutorials, overviews, and conceptual guides that explain the why and how behind your API. This is where your writers apply the style and voice guidelines from your CDG. Generated documentation, on the other hand, is automatically created from your API’s definition file, like an OpenAPI (Swagger) specification. This content provides the technical reference for endpoints, parameters, and responses. A robust content platform can ingest these specifications and render them as interactive documentation, blending them seamlessly with the authored content to provide a complete picture for developers.
Interactive API Testing and Standards
Modern API documentation goes beyond static text. The best documentation portals allow developers to interact with the API directly from the browser. This "try it out" functionality is a game-changer for the developer experience, as it lets them make live API calls and see real responses without having to set up a separate environment. This hands-on approach accelerates learning and troubleshooting. When you build your documentation portal, incorporating interactive testing is key. It transforms your documentation from a simple reference guide into a powerful, practical tool that helps developers build successful integrations with your product faster.
The Business Impact of a Content Operations Platform
A well-defined Content Development Guide provides the blueprint for great content, but a content operations platform is the engine that brings that blueprint to life at scale. When your strategies for style, structure, and reuse are supported by the right technology, the impact goes far beyond just creating better documents. It translates into measurable business results, including faster production cycles, significant cost savings, and an improved customer experience. This is where the upfront investment in building a solid information architecture truly pays off, transforming your technical documentation team from a cost center into a strategic asset that drives revenue and customer loyalty.
Faster Publishing and Time Savings
One of the most immediate benefits of combining a solid content strategy with a dedicated platform is a dramatic increase in speed. When content is structured into reusable components, writers don't have to start from scratch for every new document or update. This modular approach, managed within a Component Content Management System (CCMS), allows teams to assemble documentation quickly and efficiently. We've seen customers publish content up to 60% faster after implementing a content operations stack. This agility means you can release documentation in sync with product updates, respond to customer feedback more quickly, and get critical information to market without delay.
Significant Cost Reduction Through Reuse
Content reuse is about more than just efficiency; it's a powerful cost-control strategy. Every time you can reuse a component instead of writing, editing, and reviewing a new piece of content, you save time and money. This is especially true for translation. Instead of translating entire documents, you only need to translate new or updated components, which can reduce content costs by up to 90%. A CDG that defines a clear reuse strategy, combined with a platform that makes it easy to manage and link reusable components, is the key to unlocking these savings. This allows you to scale your content operations without scaling your budget at the same rate.
Fewer Support Tickets and Faster Answers
The ultimate goal of technical documentation is to help users help themselves. When your content is clear, accurate, and easy to find, customers can solve their own problems without needing to contact your support team. A content operations platform enables you to deliver this high-quality content through a self-service portal that is optimized for search. When users can find answers quickly, their satisfaction increases and the burden on your support organization decreases. Companies that use a dedicated portal for their documentation often see a significant drop in customer support questions—in some cases, as much as a 40% reduction. This frees up your support agents to focus on more complex issues, improving both customer and employee satisfaction.
Practicing What We Preach: The Heretto Help Portal
It’s one thing to talk about these principles in the abstract, but it’s another to see them in action. We built our own Content Development Guide to create the very documentation you can find on our help portal. The Heretto Help Portal is our single source of truth for all product information, learning materials, and release notes. It’s built entirely within our own platform, using the same DITA-based structured content and reuse strategies we recommend to our customers. This portal serves as a living example of how a well-executed content strategy, powered by a robust content operations platform, can create a world-class self-service experience for users.
Product Documentation and Release Notes
Our portal provides comprehensive documentation for every part of our platform, including the Heretto CCMS, our Deploy API, and the Portal itself. Because we use a unified content source, we can ensure that information is consistent across all product lines. When we update a feature that affects multiple components, we update a single source topic, and that change is automatically reflected everywhere it appears. This approach is especially valuable for our release notes, which are generated from the same content repository. This ensures that our customers always have access to the most accurate and up-to-date information about our products.
Learning Materials and Support Access
Beyond just technical references, the Heretto Help Portal is designed to be a complete learning resource. It contains guides and tutorials that walk users through how to use our tools to create, manage, and publish their own content effectively. By providing these educational materials alongside our product documentation, we empower our customers to become experts in their own right. The portal is structured to guide users from basic concepts to advanced strategies, helping them get the most value out of our platform. It’s the practical application of every principle we’ve discussed, designed to provide clear, helpful answers whenever our customers need them.
Building a Foundation for Scalable Content
There are ongoing discussions and debates in the DITA world about the best approaches to writing structured, topic-based content. In our Style Guide, Information Model, and Strategies we take a stance, at least implicitly, on some of these issues. But those stances, like the guidelines, are malleable. We consider the writing methodologies we use to be malleable so we can adapt if our needs change, which they often do. Again, that’s why the CDG itself is a guide, not a rulebook.With that said, you may still run into things in the CDG that baffle or befuddle you. Ask us about those things! Maybe there’s a particular guideline that strikes you as odd. Maybe you can help us rethink our approach, or perhaps we just need to explain ourselves more clearly. Either way, we’d love to hear from you.
Frequently Asked Questions
Is creating a full Content Development Guide really necessary, especially for a small team? Yes, absolutely. Think of it as the foundation for your house. You can build without a solid foundation, but you'll constantly be fixing cracks later. A CDG establishes consistency from day one, which makes onboarding new writers much smoother and ensures your content scales effectively as your team and product grow. Starting early saves you from a massive content cleanup project down the road.
What's the best first step to creating our own CDG? Start with your style guide. It's often the easiest pillar to build because you can lean on established manuals like Chicago or APA for a baseline. Have a team meeting to agree on the basics: voice, tone, and common terminology specific to your product. Documenting these simple decisions gives you immediate momentum and a tangible asset you can start using right away.
You mention the "every page is the first page" approach. When is it better not to follow that principle? That approach is ideal for web-based help portals where users can land on any page from a search engine. However, you should disregard it when creating content that is meant to be read sequentially, like a printed manual, a PDF guide, or a step-by-step onboarding tutorial. In those cases, the narrative flow of the entire document is more important than making each individual topic a standalone entry point.
How does a Content Development Guide work with a platform like the Heretto CCMS? A CDG provides the rules, and a CCMS gives you the tools to enforce and automate them. For example, your information model might define how to structure a task topic. Inside the CCMS, you can create a template that guides writers to follow that structure correctly. The platform makes it easy to implement your reuse strategy, manage versions, and publish content, turning the principles in your guide into your team's daily workflow.
My team doesn't use DITA. Can we still apply the principles from your CDG? Definitely. While our examples are DITA-based, the core pillars of Style, Information Model, and Strategy are universal to any technical writing team. You can still define your company's voice, decide how to structure different types of articles, and create a strategy for reusing content. The goal is consistency and scalability, and those are important regardless of the authoring format you use.
Key Takeaways
- Establish Your Content Blueprint: A strong Content Development Guide acts as your team's single source of truth, built on three core pillars: a style guide for voice and tone, an information model for DITA structure, and a content strategy for reuse and organization.
- Adapt the Framework to Fit Your Needs: Treat your guide as a starting point, not a rigid set of rules. Customize its principles to fit your specific industry requirements, audience needs, and publishing goals for maximum effectiveness.
- Connect Strategy to Technology for Real Results: A guide provides the plan, but a content operations platform is what executes it at scale. This combination drives faster publishing, reduces costs through reuse, and improves the customer experience by enabling self-service.
