Scriptorium Publishing

content strategy consulting

Sturm und DITA-Drang at tekom

November 16, 2015 by

This year’s tekom/tcworld conference reinforced the ongoing doctrinal chasm between North American technical communication and German technical communication.

I am speaking, of course, of the proper role of DITA in technical communication. If any.

Executive summary: There may be a valid use case for German non-DITA CMS systems, but vendors are shooting themselves in the foot with factually inaccurate information about DITA as a starting point for their arguments.

The program this year included several presentations, in both English and German, that provided the German perspective on DITA. They included the following:

The DERCOM effect

We also heard a great deal from a new organization, DERCOM. Founded in 2013, this organization is an association of German CMS manufacturers (the acronym sort of works in German) and includes Schema, Docufy, Empolis, Acolada, and three other member companies.

DERCOM has released a position paper entitled “Content Management und Strukturiertes Authoring in der Technischen Kommunikation” or (as you might expect) “Content Management and Structured Authoring in Technical Communication.” This document is available both in German and in English translation. Unfortunately, the link seems to be obfuscated. Go to the main DERCOM page and find a clickable link under “News.” DERCOM member Noxum has a direct link for the German version.

Uwe Reissenweber explicitly introduced his presentation as providing the official position of DERCOM.

Note that he used the German word “Lobbyist,” but perhaps “advocate” would be a better English translation than “lobbyist” since the latter term is so loaded with negative political connotations. Marcus Kesseler said that he was not speaking for DERCOM but rather for Schema in his individual presentation. Here is what I observed across the various presentations:

  • There was remarkable uniformity in the statements made by the various DERCOM members, even when they said they were speaking for their employer rather than the association.
  • There were a number of talking points that were repeated over and over again.
  • The descriptions of DITA were so technically inaccurate that they destroyed the credibility of the speakers’ entire argument and made it rather difficult to extract valid information.

For example, Uwe Reissenweber asserted that the DITA specialization mechanism, if used to create new elements (as opposed to removing them), does not allow for interoperability with other environments. That is, once you create new, specialized elements, you can no longer exchange your content with other organizations. This statement is technically inaccurate and betrays a fundamental misunderstanding of specialization. When you create a new element (for example, a warning), you base it on an existing element (for example, note). Because DITA maintains inheritance information, a downstream user would know that the warning element is based on note and can process it as a regular note element via a fallback mechanism. This is a critical—and unique—feature of the DITA architecture. Marcus Kesseler asserted that vendor lock-in with DITA-based content is no different than a system (like his) that uses a proprietary content model because so much of the business logic is tied up in the CMS rather than the content model. This overall accuracy of this statement depends on how tightly business processes and other information are bound into the CMS. But it seems indisputable that it would be easier to move DITA content from CMS A to CMS B (with any attendant business logic issues) than it would be to move XML Flavor A from CMS A to XML Flavor B in CMS B. In the second case, you have to move all of the business logic and worry about possible incompatibilities between XML Flavor A and XML Flavor B. “You can’t learn specialization in an afternoon.” This is a completely true statement from Uwe Reissenweber to which I say, with great professionalism, “SO WHAT??” Surely we are not advocating the idea that anything that takes more than an afternoon to learn cannot be worth the effort. After hearing these statements and others (see my Twitter feed for increasingly agitated coverage), it becomes difficult to take any of the presenters’ arguments seriously. And this is unfortunate, because I do want to understand their position. Kesseler, for example, displayed a chart in which he made the case that business logic is embedded either in the CMS or possibly in the DITA Open Toolkit, but not in the core DITA topics.

His Schema co-founder, Stefan Freisler, believes that only 5–10% of return on investment realized from a CMS system is in the content model. Instead, the vast majority of the value resides in the workflow layer.

These are interesting points and worthy of further discussion.

DITA support in DERCOM CMSs?

Eliot Kimber, who has a lot more patience than I do (also, I had a scheduled meeting), stayed through a heated post-presentation Q&A with Kesseler. Kimber had this to say in his trip report:

It was an entertaining presentation with some heated discussion but the presentation itself was a pretty transparent attempt to spread fear, uncertainty, and doubt (FUD) about DITA by using false dichotomies and category errors to make DITA look particularly bad. This was unfortunate because Herr Kesseler had a valid point, which came out in the discussion at the end of his talk, which is that consultants were insisting that if his product (Schema, and by extension the other CCMS systems like Schema) could not do DITA to a fairly deep degree internally then they were unacceptable, regardless of any other useful functionality they might provide.

This lack of support is another starting point for discussion. (I would also note that it’s often not the Evil Consultants, but rather the Opinionated Clients, who are insisting on DITA.)

With a proprietary content model, you are putting your trust and a good bit of your ability to execute in the hands of your CMS vendor. Provided that the vendor does a good job of introducing new features that meet your needs, you could have a long and mutually beneficial relationship. But what if your vendor starts to falter? What if they are acquired and change their strategy to something that doesn’t meet your requirements? DERCOM members are asserting first that they are better at adapting information models to the needs of their clients and second, that the content model provides only a small part of the value of the CMS.

Do you throw your lot in with a vendor, their release cycle, their software development/R&D efforts, or do you choose to rely on a standard and therefore rely on the OASIS technical committee, with all of the advantages and disadvantages of the committee-based standards-building process?

If the content model is largely irrelevant to the CMS functionality, why not just have the best of both worlds and support DITA inside the Very Superior DERCOM systems? Some of the vendors are doing just that. Empolis supports DITA both in its core CLS offering and in a new, low-cost SaaS system that is under development.

It remains as an exercise for the reader to understand why the other vendors are not following suit. Eliot says this:

DITA poses a problem for these products to the degree that they are not able to directly support DITA markup internally, for whatever reason, e.g., having been architected around a specific XML model such that supporting other models is difficult.So there is a clear and understandable tension between the vendors and happy users of these products and the adoption of DITA. Evidence of this tension is the creation of the DERCOM association (, which is, at least in part, a banding together of the German CCMS vendors against DITA in general, as evidenced by the document “Content Management and Struktured Authoring in Technical Communication – A progress report”, which says a number of incorrect or misleading things about DITA as a technology.

During the German-language Intelligente Information panel, Professor Sissi Closs pointed out the importance of DITA as a multiplier. She mentioned that widespread adoption of DITA would lead to a network effect, in which the standard becomes more valuable because more and more people are using it and therefore training, support, community, and qualified employees are more readily available.

Some statistics

In North America, DITA is the clear leader in XML-based content work. We estimate that at least 80% of structure implementations are using DITA. The equivalent number for Germany is in the 5-10% range, based on research done by tcworld.

This chart was shown in Reissenweber’s presentation and attributed to tcworld as of 2015:


Here is my English translation. In each grouping, the upper bar is for software companies and the lower bar for industrial companies.


Scriptorium’s perspective

For Scriptorium consulting projects, we use a standard methodology with roots in management consulting. In the assessment phase, we develop the following:

  • Business goals for the organization
  • Content strategy to support the identified business goals
  • Needs analysis
  • Gap analysis
  • Requirements
  • Implementation plan, ROI, and budget

The decision whether or not to use DITA is generally made in the requirements phase. Most North American companies, at this point in time, assume that DITA is the path of least resistance because of the large numbers of authoring tools, CMS systems, and supporting systems (like translation management and content delivery platforms) that support it.

DERCOM companies will have difficulty making inroads into this market without an affirmation that they can provide DITA support. Any advantages that they might have in workflow or editorial management are irrelevant because they will be ruled out as a prospective vendor by the DITA requirement. Additionally, most of these vendors do not have much presence in North America, so support, training, and maintenance are a risk.

Classic case of disruption

In Germany, the DERCOM vendors are clearly dominant at this time. However, their continued insistence that their technology is superior and the upstart DITA-based options should be ignored follows the classic pattern seen with disruptive technologies. When a disruptive technology offers a clear advantage that is different from the main feature set of the incumbent approach, the incumbents have much difficulty responding to the new challenge.

In the case of DITA, the disruptions are in the following areas:

  • A wide variety of options at each point in the tool chain (authoring tool, content management system, translation management system, content delivery portal, and others)
  • Incremental implementation. Because DITA can work both on a file system and on a CCMS, organizations can opt for an incremental implementation, where pilot projects are built and validated on the file system before CCMS selection begins.
  • Open standard. Interested parties can participate in the standards-development process through OASIS. Vendor assessment is based on conformance to the standard, which makes evaluation across vendors easier for the buyer. Content exchange is easier to implement for the buyer.
  • The ecosystem of DITA architecture, software vendors, consultants, open-source community, and more. (Take a look at the DITA projects available just on GitHub.)

NOTE: Translations from German are mine. If the original authors would like to provide a better or alternate translation, please leave a comment. My tweets of German presentations are real-time translations by me. I apologize in advance for any errors.

Additional reading (if by some miracle you made it this far):

Content strategy versus scope creep

November 9, 2015 by

Content strategy implementations require substantial planning, coordination, and hard work. The effort involved in keeping planned work moving along can be difficult. Scope creep–discovering new requirements along the way–can potentially derail your entire effort if you’re not careful.

cartoon  caricature of a villain

Scope creep depicted as a quintessential cartoon villain. (image: J.J. at the English language Wikipedia)

A former colleague of mine once personified scope creep as a shady character who was always up to no good. The scope creep would quietly wait in the shadows until a project was well underway. Then, without warning, his sinister plan would be revealed, wreaking havoc upon the project and its team.

This characterization of scope creep not only injected humor into an otherwise stressful situation, but it allowed the project team to personify and target the problem and not the people who unwittingly created it.

Scope creep can manifest in a content strategy implementation in many ways. Examples include:

  • new outputs: You may have planned for PDF and HTML5, but product teams are now requiring native Android or iOS output.
  • new inputs or changing technology: The data center has been quietly working on a server update, and the information delivery to your team now uses a new format or schema.
  • additional stakeholders: Sales and marketing suddenly have a strong interest in (and a compelling argument for) managing content in your intended system.
  • team changes: Your XSLT expert has been reassigned to a critical web project, and you have inherited another developer to fill the gap.
  • changes in deadlines: Another project that some team members are also involved in now has an earlier release date. Or worse–delivery of technology that you require has been delayed, and pushing your schedule out means that your team members’ other responsibilities are now in jeopardy.

Resolving these types of issues within the scope of your implementation project is simply not possible. Addressing one problem will likely create another. For example, adding support for additional content types will likely require additional output formats and push out your deadline.

Rather than combat scope creep head on, build a strong defense against it. Fewer logistical gaps in your project limit the chances of scope creep making an appearance. You must have clear requirements and firm commitments from all involved parties up front. Detail all dependencies, and plan out alternative approaches should any of those dependencies change.

Perhaps the best defense against scope creep is the ability to say “no”. It is perfectly acceptable to push back on new requirements and to deny other changes once your project is underway. However… you must have a strong business case and must plan your project accordingly from the beginning and obtain full agreement on the planned project scope first. Leave no stone unturned as you engage others in your organization during the discovery phase of your content strategy.

Fewer unknowns create fewer logistical gaps in your content strategy, and thus fewer opportunities for scope creep infiltration.

New LearningDITA course: reference and glossaries

November 2, 2015 by

Thank you all for your great response to our free DITA courses at (over 500 registrants and counting)! Now that you’ve got your feet wet with the Introduction, concept topic type, and task topic type courses, are you ready for the next challenge?

Dave Young - originally posted to Flickr as surfer chicks

Dave Young – originally posted to Flickr as surfer chicks

Today we are releasing another course in our series: The DITA reference and glossary topic types.

This new class on introduces three additional topic types: reference, glossary entry, and glossary group. The course and supporting videos were created by a Scriptorium team led by Jake Campbell (with help from Gretyl Kinsey and me).

The course includes four lessons on:

  • Lesson 1: Creating a reference topic
  • Lesson 2: Best practices for reference topics
  • Lesson 3: Creating a glossary topic
  • Lesson 4: Best practices for glossary entries

With guided exercises and on-your-own work, this course should help round out your familiarity with the common DITA topic types.

As always, we welcome additional content through the GitHub repository. Take a look at the project roadmap and see where you can contribute! To get notifications about new content on the site, sign up for announcements. You can also sign up during the site registration process.

Special thanks to the Learning DITA sponsors: oXygen XML Editor, The Content Wrangler, and easyDITA.

Content strategy triage

October 26, 2015 by

Who lives? Who dies? Who do you fight to save?

This article is a summary of a presentation first delivered October 21, 2015, at LavaCon in New Orleans.

Triage is a medical concept. If you have a large number of patients flooding in for treatment, you use triage to decide who gets treated first (or at all). Patients are color-coded as follows:

  • Red (immediate): Need immediate treatment.
  • Yellow (delayed): Need treatment, but can wait.
  • Green (minor): Can wait longer than yellow.
  • Black (deceased): either deceased or cannot survive their injuries.

If you think this is a bit morbid, you’re right. If you immediately wonder how to combine the concept of triage with content strategy, read on!

In theory, you want to find the perfect project in which you have high visibility, high return on investment (ROI), and low risk.

Venn diagram with circles for high visibility, high ROI, and low risk

Content strategy, the theory

The reality is that you are probably going to have to settle for two out of three:

Same Venn diagram as previous, but the intersection of all three circles is labeled "As if..."

Content strategy, in practice

We divide content strategy efforts into three broad phases:

  • Pilot
  • Main effort
  • Ongoing effort

For a pilot project, you want high visibility and low risk. This maps to red triage–do it immediately!

Another Venn diagram with highlighting where low risk intersects with the other two factors.

Ideal pilot project is high visibility and low risk. High ROI and low risk is acceptable.

The purpose of a pilot project is survive and advance.

Pilot projects do not need to prove cost savings, or show huge improvements. They are intended to convince the Money People that your content strategy has merit, and that they should continue to invest in it. Therefore, the ideal pilot is the smallest, easiest possible project that will gain momentum for the overall effort. A high-visibility improvement that is easy to achieve is a good choice.

After the pilot phase, you move into the main phase of the project. Here, you want to focus on high-impact projects. You take a few more risks because you expect a high ROI. These projects should focus on visibility and ROI. This is the yellow triage tag; things that are important, but can wait a little while.

Venn diagram with intersection of high visibility and high ROI highlighted.

The intersection of visibility and ROI is where you find the main project effort.

If you look at content strategy over time, you can see a pattern emerging. Early on, you need low risk and high visibility. Later, you focus more on ROI. You can also gradually increase the complexity of your projects as your content strategy team gains experience and knowledge.

Bar chart shows risk, ROI, visibility, and complexity. Risk lowest, then complexity, then ROI. Visibility is very high.

For a pilot project, you need high visibility and low complexity.

You can gradually increase the risk of your projects and the overall complexity as your team gains knowledge and experience.

Same four bars as previous, but now risk and complexity are high. Visibility and ROI are lower.

As you gain content strategy experience, you can increase the complexity of your projects.


Content strategy triage helps you assess your projects. Measure the following factors:

  • Risk
  • ROI
  • Visibility
  • Complexity

Map each project against these factors, and you will be able to determine which projects should be done early on and which can (and should) wait until you gain more experience.

One of the keys is to figure out what sort of projects should be black-tagged. They may or may not be dead already, but you cannot save them. What sort of content strategy challenges might cause you to just walk away instead of trying to fix it and, as a result, not saving a bunch of other content strategy patients on whom you could have spent your resources instead??

Content should not be an obvious tourist

October 19, 2015 by

When you travel, do people ask you for directions and address you as if you live in the area? I’ve had that happen a few times, and friends and colleagues have shared similar experiences.

You may not stand out as an obvious tourist on your travels. But does the content you distribute fit in as well across different environs?

No, not everyone speaks English

The world is now a global economy. If you expect to reach the widest audience possible for your products and services, localizing your content is a must—and in some cases, it’s a legal requirement to sell in other countries.

Also, making assumptions that everyone speaks a particular language (cough, English, cough) is a really bad idea when traveling, and it’s really, really bad idea in business. Don’t be one of those arrogant tourists (or companies!) who thinks everyone will adapt to them.

Dress for your location

tourist looking at map

Jean-François Gornet

When traveling, it’s a good idea to bring clothes that are a good match for the location’s climate and attitude. Wearing the wrong clothing makes you really stand out, and not in a good way. It’s also downright uncomfortable.

The formats in which you present your content require similar thought. If your customers are using tablets and phones to access information, distributing your content just as PDF documents is not the right fit. Also, does your web content display well in both desktop and mobile browsers?

Get feedback from your customers on how they want to consume your content, and adapt your formats accordingly. Otherwise, users will go elsewhere.

How else can companies make sure their content isn’t an obvious tourist? Leave your tips in the comments.

The commodity trap

October 13, 2015 by

In a recent post on lean content strategy, I wrote about a focus on waste reduction:

After creating a nice automated XML-based process, waste in formatting is eliminated, and we declare victory and go home. Unfortunately, the organization is now producing irrelevant content faster, and the content organization is now positioned as only a cost center.

Is your content perceived as a commodity?

Given a critical mass of content, a move away from desktop publishing (DTP) and into XML publishing offers compelling benefits—faster publishing, more efficient translation, efficient reuse, and so on. (Try the XML business case calculator to see whether it makes sense for your situation.)

Over the past decade or so, many organizations have moved into XML. For the most part, they have implemented what we might call XML Workflow Version 1, which has the following characteristics:

  • Focus on automation, especially in translation, as the justification for the change.
  • Refactoring content to improve consistency, which improves efficiency for authors and translators.
  • Reducing formatting edge cases that are difficult to automate.

All of these improvements are useful and necessary, but they focus on how information is encoded. Many organizations are now experiencing pricing pressure from management. Because the content creators have shown that they could be more efficient, management assumes that there must be more efficiency gains available.

Because the justification for XML Workflow Version 1 positioned content as a commodity, management now assumes that content is a commodity.

If you are in the commodity trap, you will experience the following:

  • Pressure to lower content creator costs via staff reductions, outsourcing, and so on
  • A lack of interest in content initiatives other than cost reduction
  • A flat or declining budget
  • A focus on lowest-cost suppliers across all aspects of content and localization and on commodity metrics, such as price per word
  • No budget for staff development

So how do you avoid the commodity trap?

First, it is a fact that XML Workflow Version 1 is mostly about efficiency—and many content groups need to be more efficient. When negotiating for a shift to XML, however, make sure that your argument includes XML Workflow Version 2, in which you can begin to use XML in more sophisticated ways. For instance:

  • Integrate XML-based content with information derived from business systems (such as SAP)
  • Deliver content to other business systems (such as software source code) in a compatible format to provide for better integration and collaboration across the organization
  • Improve the semantics of content (for example, embed an ISBN number with a book reference or a part number with a part reference) and provide for useful cross-linking
  • Focus on touchpoints in the customer journey and how to deliver information that supports the journey
  • Improve the localization and globalization process to deliver information that meshes with each locale, rather than just a somewhat awkward translation

Efficiency in content creators is a means to an end. By freeing content creators from formatting responsibilities and from copying/pasting/verifying repeated information, you can make them available for more high-value tasks. Avoid the commodity trap by ensuring that your content vision goes beyond efficiency and automation.

Unsung heroes of DITA (premium)

October 6, 2015 by

For some content developers—especially those using DITA for the first time—any features of DITA that go beyond the basics can seem intimidating. But sometimes, a special feature of DITA might be exactly what an organization needs to solve one of its content problems and save money. Features like conref push, subject scheme, and the learning and training specialization could play a powerful role in your content strategy—and they’re not as difficult to use as you might think.

Conref push

conref push
Conref push has the power to:

  • Push content into a topic. With conrefs, you can pull content into a topic by reference. However, with conref push, you can insert or “push” content from a source topic into another topic. That way, when you open your published topic, you can actually see the content from the source topic. You might use conref push to add a step to a task or replace an item in an unordered list.
  • Push content into a map. Conref push isn’t limited to adding or replacing elements in a topic—you can also use it to insert content into a map. This might include adding or replacing a topicref, changing a navtitle, or updating the map metadata. Conref push would be especially useful for organizations that have maps updated by people in multiple departments.
  • Facilitate ultimate reuse! If you have reusable content, you can store it in a source topic and use conref push to insert it into the relevant destination topics. With conref push, you can modify topics by adding or replacing elements in a way that the original author never conceived.

Conref push works by looking for IDs in your destination topic specifying where the pushed content should go:

<task id="contentstrategy">
<title>Developing and implementing a content strategy</title>
      <step id="establish-goals"><cmd>Establish implementation goals and metrics.</cmd></step>

Then, in your source topic, conref push uses the conaction attribute to replace an existing element:

<step conref="contentstrategy.dita#contentstrategy/establish-goals" conaction="pushreplace"><cmd>Define implementation goals and metrics.</cmd></step>

Conref push also allows you to push content before or after an existing element. If you use the conaction attribute with a value of pushbefore or pushafter, you must do so in conjuction with another conaction attribute with a value of mark to specify the location of the pushed content:

<step conaction="pushbefore"><cmd>Identify and interview stakeholders.</cmd></step>
<step conref="contentstrategy.dita#contentstrategy/establish-goals" conaction="mark"><cmd/></step>

<step conref="contentstrategy.dita#contentstrategy/establish-goals" conaction="mark"><cmd/></step>
<step conaction="pushafter"><cmd>Define roles and responsibilities.</cmd></step>

Once you’ve set up your IDs in your destination topics and your conaction attributes in your source topic, you’ll need to add the source topic to the other topics via a map to see conref push in action.

If you need to reuse content across multiple departments in your organization, conref push is the perfect hero for the job. Suppose you have two teams—tech comm and training—that share a lot of instructional content. The training team needs to use the instructions in the tech comm team’s topics, but they also need to add some information that is specific to the training department.

The tech comm team doesn’t want to be saddled with adding training-specific content to their topics (or setting up the conditions that would require). With conref push, the training team can add their own content to the topics instead—problem solved!

Subject scheme

subject scheme
Subject scheme has the power to:

  • Define custom controlled values in a map. Much like a standard DITA map uses topicrefs to define a collection of topics, a subject scheme map uses key definitions to define a collection of controlled values. This means you can create a taxonomy of custom values without having to write a specialization. To use a subject scheme map, you must reference it in the highest-level DITA map that needs to use the controlled values within it.
  • Manage relationships between controlled values. A subject scheme map sets up a hierarchy of controlled values and allows you to divide these values into categories. You can also bind the custom controlled values you create to metadata attributes.
  • Build the framework for ultimate faceted search! A subject scheme map allows you to classify large amounts of information. The values you define can be used as facets to set up a controlled, sophisticated search of your content. To take advantage of this power, you’ll need content management and authoring tools that support faceted search.

A subject scheme map defines controlled values, or keywords that identify metadata attributes, using the subjectdef element. The highest-level subjectdef elements define categories of metadata, and their child subjectdef elements define the values. By adding further levels of child subjectdef elements, you can divide these values into sub-categories:

  <subjectdef keys="vehicles">
    <subjectdef keys="car"/>
    <subjectdef keys="motorcycle"/>
    <subjectdef keys="boat">
      <subjectdef keys="racing"/>
      <subjectdef keys="fishing"/>

Once you’ve defined your custom controlled values, you can use the enumerationdef element to bind them to metadata attributes:

  <subjectdef keys="vehicles">
  <attributedef name="audience"/>
  <subjectdef keyref="vehicles"/>

With a subject scheme map, you don’t have to store attribute values in each content contributor’s DITA editor. As long as the DITA editor understands the subject scheme, the attribute values will be available to all who edit the maps or topics.

Your company might benefit from using a subject scheme map if you distribute a large number of products and need a better way to categorize them so that they are easier to find. For example, if your company sells engines, your customers should be able to search for the documentation on the engine they need according to criteria such as the relevant type of vehicle (car, motorcycle, boat), release version (1.0, 1.1, 2.0), and locations sold (United States, India, Japan).

By defining this information in a subject scheme, your customers will be able to find your content in a more targeted way than they can using a table of contents, an index, or full text search—the usual methods available with basic DITA.

Learning and training

learning and training
The learning and training specialization has the power to:

  • Structure a curriculum using specialized DITA. Just as standard DITA can be used to structure technical content in a manual with sections, the learning and training specialization can structure learning content in a course with lessons. Each lesson (or the whole course) can have a plan and an overview before it, and a summary and an assessment after it. Learning content topics can also contain standard concept, task, and reference topics.
  • Create and manage tests and quizzes. The learning and training specialization includes the learning assessment topic type, which contains elements for different types of test questions. In a learning assessment topic, you can store a question, its answer, the number of points it’s worth, and some feedback for the user. This puts the test and the answer key in a single source, which makes it easier to update the assessment material.
  • Develop amazing e-learning! With the learning and training specialization, you can instruct students over the web with interactive courses and grade their assessments automatically. (See for an example!)

With the learning and training specialization, you can structure a course to follow this ideal framework:


But what happens when you need learning content in both the virtual and the physical classroom? Because the learning and training specialization was designed for e-learning, it only provides types of assessment questions that could be answered electronically—such as true/false, matching, multiple choice, sequencing, and open-ended questions—by default.

However, the learning and training specialization can be further specialized and customized to suit your needs. For example, you could specialize the open question type to include blank lines for a student’s handwritten answer. You could also use specialization to create new question types intended for use in a physical classroom, such as filling in a blank or circling a word or phrase.



Conref push, subject scheme, and the learning and training specialization are all part of DITA 1.2, which means that they can be used together. You might…

  • use conref push to keep your subject scheme map up-to-date,
  • reuse content between lessons or tests with the help of conref push, or
  • keep track of controlled values related to an e-learning course using a subject scheme.

You might even solve your content problems by using all three. Your strategy doesn’t have to be limited to just one of these features—if you have a strong business case for it, feel free to call in the whole team!

These unsung heroes of DITA may not have a place in the spotlight (yet), but the more they’re used, the more they’ll catch on. As DITA 1.3 becomes more established and more widely supported, the features introduced with DITA 1.3 will become the new unsung heroes, which will give features from DITA 1.2 such as conref push, subject scheme, and the learning and training specialization the chance to become leaders of a bigger and better team.

If you’re having issues with your content and you think these heroes could help, don’t be afraid to call them in—they’re not as intimidating as they look, and they just might be able to save the day!
unsung heroes

Lean content strategy

September 28, 2015 by

Lean manufacturing begat lean software development which in turn begat lean content strategy.

What does lean content strategy look like?

Here are the seven key principles of lean software development.

  1. Eliminate waste
  2. Build quality in
  3. Create knowledge
  4. Defer commitment
  5. Deliver fast
  6. Respect people
  7. Optimize the whole

How well do they map over to content strategy?

1. Eliminate waste

Waste bin labeled TEAM WASTE

Eliminate waste // flickr: jeffdjevdet

Interestingly, many content strategy efforts focus only on eliminating waste.

Here are some common types of waste in content:

  • Waste in formatting (formatting and reformatting and re-reformatting)
  • Waste in information development (end users do not want or need what’s being produced)
  • Waste in delivery—information cannot be used by end user because it’s not in the right language or the right format
  • Waste in review—oh, so much waste in the review cycles

Too often, strategy projects end with waste reduction. After creating a nice automated XML-based process, waste in formatting is eliminated, and we declare victory and go home. Unfortunately, the organization is now producing irrelevant content faster, and the content organization is now positioned as only a cost center. Typically, the next step is that executive management demands additional, ongoing cost reductions rather than looking at possible quality improvements. Eliminating waste cannot be the only priority. (I expanded on this theme in The commodity trap.)

Ellis Pratt has a great lightning talk overview of types of waste in lean content strategy. I believe that he is the first person to combine the concept of lean manufacturing/lean software development with content strategy.

UPDATE (January 5, 2016): And here is a presentation from Joe Gollner on Lean DITA.

2. Build quality in

How do you measure quality in content? “I know it when I see it” is really not a good answer. Some content quality factors include:

  • Writing quality—mechanics and grammar
  • Usability—the ease of access to information
  • Technical accuracy
  • Completeness
  • Conciseness

All of which Scriptorium notoriously put together into the QUACK quality model.

Building quality in means that the process of creating content supports a high-quality end result. Accountability in content reviews is one technique; content validation to ensure it conforms with required structures another. Software authoring assistance can help with writing quality.

The process of creating and managing content should assist the content creator in producing high-quality information.

3. Create knowledge

The fundamental purpose of content is of course to create and disseminate knowledge. As an aspect of lean content strategy, we can identify several groups that need knowledge:

  • End users need information to use products successfully.
  • Content creators need to accumulate domain knowledge, process knowledge, and tools knowledge to become better at their jobs.
  • The user community needs a way to share knowledge.

Any content strategy must include ways to support knowledge creation inside and outside the organization.

4. Defer commitment

Our basic process for content strategy is to first identify key business requirements, and then build out an appropriate solution. The temptation, however, is to make critical decisions first, especially in tool and technology selection. Defer commitment means that you should:

  • Store content in a flexible format that allows for multiple types of output.
  • Keep your options open on deliverable formats.
  • Be open to adding new content based on user feedback or other new information.
  • Assess localization requirements regularly as business conditions change. Look at a list of supported languages as an evolving set, not as set in stone forever.

Also identify areas where commitment is required. If your content needs to meet specific regulatory requirements, these requirements change very slowly. Don’t defer a commitment to a legal requirement.

5. Deliver fast

This is true across the entire effort: content creation, management, review, delivery, and governance. Reexamine those six-month production cycles and lengthy review cycles, and find ways to shorten them.

Keep up with new products and new output requirements. Don’t let the market pass you by.

6. Respect people

Lots to think about in this area, but here are some basics:

  • Content creators: Respect their hard-won product and domain expertise.
  • End user: Respect the end user’s time and provide efficient ways to get information. Do not insult end users with useless information, like “In the Name field, type your name.”
  • Reviewer: Respect their limited time and help to focus reviews on adding value.

7. Optimize the whole

Optimizing inside a content team will only take you so far. The content team must reach into other parts of the organization, where they can:

  • Identify the origin of information and use it. For example, if product specifications are stored in a product database, then product datasheets should pull information directly from the database. Here’s what they should not do: Export from the product database to an Excel file, send the Excel file via email to the content creator, have the content creator copy and paste from the Excel file to the product data sheet file.
  • Identify content reuse across the organization and eliminate redundant copies.
  • Understand silos and why they occur. Find ways to eliminate or align silos.
  • Reduce the number of content processes in the organization.


Lean content strategy. What do you think?

Roles and responsibilities in XML publishing

September 14, 2015 by

The roles and responsibilities in an XML (and/or DITA) environment are a little different than in a traditional page layout environment. Figuring out where to move people is a key part of your implementation strategy.

Flamenco dancers and singer on a dark stage
In an unstructured (desktop publishing) workflow, content creators need a variety of skills. The three most important are:

  1. Domain knowledge (expertise about the product being documented)
  2. Writing ability (duh)
  3. Knowledge of the template and formatting expertise in the tool being used

For a structured workflow, the first two stay the same, but paragraph and character styles are replaced by elements. Formatting expertise is less critical—the formatting is embedded in a stylesheet, which is applied to content when it is time to create output. Knowledge of copyfitting and production tricks is no longer relevant and can even be detrimental if the content creator insists on trying to control the output by overriding default settings.

The content creator needs less template and formatting expertise, especially if the content is highly structured and provides guidance on what goes where. Generally, content creators need to focus more on how to organize their information and less on how to format it.

The role of the technical editor (assuming you are lucky enough to have one) also changes. Document structure is enforced by the software, so technical editors can focus on overall organization, word choice, and grammar. Technical editors are often responsible for reviewing large amounts of content. This perspective can be helpful in establishing an information architecture.

Speaking of information, we have the information architect, who is responsible for determining how information should be organized and tagged. Typical tasks for the information architect are:

  • Developing guidelines for topic-based authoring (for example, how big should a topic be?).
  • Establishing rules for tagging. For example, when should an author use the <cite> tag and when the <i> tag?
  • Organizing shared content and establishing guidelines for reuse.

The equivalent responsibilities were typically handled by the technical editor and the production editor in an unstructured workflow.

In an unstructured workflow, production editors are responsible for finalizing the layout/composition of unstructured content. They typically have deep expertise in the publishing tool and know all of the tricks to make output look good. Very often, production editors are permitted to override templates to copyfit pages and make the final result look better.

The role of the stylesheet programmer is new in an XML workflow and replaces the production editor. The stylesheet programmer creates a script that transforms XML directly into output (such as PDF or HTML). In effect, the handiwork of the production editor is replaced by a script. Stylesheet programmers need a thorough understanding of XML and especially of publishing scripts, such as XSLT, but they need almost no domain knowledge.

Here are the typical roles in a structured workflow:

Role Tags Publishing Domain
Content creator User User Advanced
Information architect Expert User Basic
Stylesheet programmer User Expert Basic
Reviewer None None Expert

Did we miss any? What do you think?

Portions excerpted from our Structured authoring and XML white paper.