The Jorsek Style Guide
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 Jorsek Style Guide contains guidelines for writing and grammatically styling Jorsek 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 Jorsek 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 Jorsek in particular. If you’re in a different industry, just replace our jargon with your jargon. Similarly, our very short Punctuation topic states that Jorsek 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/.
The Jorsek Information Model
The Jorsek 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 tech 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 Jorsek 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.
Jorsek Strategies
Jorsek 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.
The Wrap Up
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.
