Four Best Practices for Sharing Content Across Departments using DITA
Many teams produce similar or identical content as that produced by teams within the same company. The promise of the Darwin Information Typing Architecture (DITA) is that you’ll be able to reuse XML content to avoid redundant work and improve content consistency. To realize this goal, you must address the four key considerations covered in this article.
1. Goals
As with any initiative, you must know the objective in order to be successful. This means that in addition to identifying what you want to achieve, the goals must be clear and quantifiable, realistically achievable, and agreed upon by all participants.
Clear and Quantifiable
How many projects have you seen fail due to vague goals, such as “We want to save money” or “We need to be more efficient”? Although these goals state intentions, they do not define success.
To define success, the goals must be clear and measurable. To clarify the goal “to save money,” you must specify an amount of money or percentage of change in costs and indicate the time period over which the cost will be reduced. Rather than a general intention, a measurable goal might be: “Reduce costs for producing online content in the technical support and technical publications departments by 10% from previous fiscal quarter starting in Q3 2017.” This goal clearly identifies what is being measured (cost of producing online content), the teams involved (technical support and technical publication departments), the anticipated change (10% cost reduction), and when the change must occur (Q3 2017).
Realistic
After you clearly define the goal, verify that it is realistic. A clear, unachievable goal does not position you for success; it sets you up for failure. Goals can be unrealistic in various ways. For example, if the stated measurable goal is to do ten times as much work with half the resources in the next quarter, then it is certainly measurable. However, it is unrealistic in that it sets criteria for success too high and does not provide enough time to realize significant change. An example of a realistic, achievable goal is: “Produce 15% more online content in the technical support and technical publications departments than in the previous fiscal quarter starting in Q3 2017 with the same staffing resources.” This goal is realistic in that it specifies a reasonable amount of measurable change.
Agreement
People reuse content for a variety of reasons; for example, some teams may want to produce more deliverables in multiple formats and others may want to consolidate redundant information and reduce the number of deliverables. Do not assume that all the stakeholders on the project share the same goals. Take the time to state the goals and validate that you all want to reuse content for the same reasons. If the goal for your team is to reduce the number of online deliverables by 25% in the Q3, make sure that the other team does not have the goal to increase the number of deliverables for that same time period.
2. Process
The process is how you string tasks together in a sequence or a series of actions to accomplish something. In the context of content creation, consistent process implementation helps authors create consistent source content.
Documented and Followed
If you have a content authoring process that is not documented, the authors are not following it. Everyone does what seems to work best for them to deliver the end result. If you do have a documented process, but the content authors are not following it, it does not count either. Take the time to find out why they aren’t following it. If it isn’t a user-friendly process, authors will create their own.
Content reuse is dependent upon consistent content creation. Consider these key process milestones when trying to share content:
When is structure ready to share?
When is content ready to share?
How will you communicate about milestones?
How will you share the structure or content?
This does not mean that all content authors must follow the exact same process – rather, you must identify the milestones where the different processes intersect and define the gating criteria for moving to the next phase in the development lifecycle.
Dependencies
One of the key dependencies that content authors must understand when creating DITA content is that they must write the content with reuse in mind. This means that they cannot include contextual references, such as “in the previous chapter,” because the topic may have different neighbors in different deliverables.
In addition, authors must use the appropriate elements in the content to produce properly formatted output. Because XML separates content from formatting, corporate styles (e.g., bold text for window titles) are dependent on the author’s use of the element wherever a window title is mentioned. Without it, the proper formatting is not applied when you generate the deliverables.
Lastly, content must be structured for reuse, which means that topics must be written at the appropriate level, and groups of topics that are candidates for reuse must be organized into collections. If you have a topic that contains ten lengthy sections and you are storing topics in a content management system (CMS) that restricts content referencing to referencing entire files, you cannot easily reuse content from that large topic. Instead, break it up into multiple topics and organize them into a map.
Stakeholders and Participants
Stakeholders are people who have an investment in making a process work. In contrast, participants are the people who not only have an investment in the process, but actually do the work. In the scenario of reusing content, stakeholders include the manager calculating the percentage of savings her team achieves by reusing content and the information architect who specifies the reuse strategy. The authors who create and share the content, as well as the deliverable specialist who creates the deliverable maps, are the participants.
To successfully share content, it is critical that everyone understands their role in content creation and reuse processes. For example, if the process states that authors must reuse product names from a master, then someone must create and maintain that library as well as communicate to authors how to reuse the names.
3. Criteria
The technical criteria for being able to reuse content are simple: the content must be valid XML, it must meet the agreed-upon quality standards, and authors must be able to find it.
Valid XML
DITA is a topic-oriented architecture, and each topic type has a specific XML structure. For example, a task topic does not allow you to have a step without including a command. To easily guarantee that the XML is valid for each topic type and map, use an editor that does not allow authors to create invalid content.
In an ideal situation, all the parties who are to share the content agree upon a consistent architecture. If all the parties are using DITA, then you know that the structure for each topic type is consistent. If you cannot all use the same architecture, agree upon a limited element list and enable a process that maps the elements of the different structures to their corresponding elements in DITA and apply a transform to create valid DITA topics and maps.
Quality Standards
To create content with a consistent quality rating, all the parties must agree upon the quality standards. In particular, it is important that you measure quality the same way. For example, if one team measures quality by checking for spelling and another team requires that the content be edited for conformance to minimalism standards, then they cannot easily share content. As with processes, you do not need to have exactly the same standards, but you must agree upon what is acceptable and what is not, as well as how you can measure it.
Storage
The primary rule for storing content is that authors cannot reuse content that they cannot find. If all the content is in the same repository, such as a source control system, but the system does not have search functionality to aid in content retrieval, then the authors cannot share easily share content.
If the content is stored in multiple repositories, but you have mechanisms in place such as federated keyword or metadata search, then authors may be able to find the content to use it. One important issue in trying to share content from multiple repositories is to ensure that authors have appropriate access permissions for each repository. Ideally, the content is stored in a component content management system (CCMS) that is DITA-aware. These repositories not only version content; they provide robust search support.
4. Architecture
Information architecture for reuse entails identifying at what level to reuse content, determining when to reuse exactly or conditionally process, and identifying content that should not be shared.
Reuse level
DITA enables reuse at every level: map, topic, and element. This means that your reuse strategy needs to address how to successfully reuse content at each level.
To reuse content at the map level, you must understand and communicate the role that maps play in organizing content. To gain the most reuse, create small maps containing sub-collections of topics that logically travel together. You can then easily include these maps in multiple deliverables and apply conditional processing if you need to produce variations of the output.
To reuse content at the topic level, create a plan by topic type. This means that you may determine that it is appropriate to reuse concept topics that cover common technologies, but that all the task topics are too specific for easy reuse.
To reuse content at the element level, identify what content to reuse and the elements to use for maximum reuse. For example, if you want to reuse product names from a master directory, then you must agree upon the element to use for product names, such as the or , element. DITA supports multiple element reuse mechanisms—content reference, key reference, and conkey reference. Determine the appropriate mechanism as part of your information architecture. If you are using a CCMS, be aware that some repositories do not support referencing elements from within a topic; you must store the element as a separate file.
Conditional Processing
After identifying information that can be used without changes, you must identify information that can be used in part or with minor changes. To use a subset of the content, you can identify elements using conditional attributes during authoring and set the appropriate conditions when you generate output. You can apply conditions at the element, topic, and map level.
As an example, you may have a project with a map that includes a submap specific to Product A; a topic within another map that applies only to Product B; and a paragraph in a topic that applies only to Product C. If you apply the product values appropriately when you generate the output for Product A, the generated deliverable contains only the content applicable to Product A. DITA provides conditional processing with three default values and DITA 1.3 supports specializing the “props” attribute to add additional custom variables.
Un-sharable Content
The old adage “Just because you can, doesn’t mean you should” applies to reusing content. Although you may have access to all the possible content, not all content has the potential for successful reuse. Content created to provide flow for linear deliverables, such as books, may include context-specific information not applicable outside of the deliverable. Another example of non-reusable content is content written for a specific deliverable, such as release note content, which is time-specific.
Summary
When all the parties can agree upon the goals, processes, reuse criterial and scalable information architecture, then you can share content. The good news is that DITA can provide the initial architecture for content reuse with collaboration. It can scale to become the common semantic currency for content interchange for your entire enterprise. You can leverage DITA at all levels of your company to reuse content starting with topics.
Initially, when you share content across departments, you start with a subset of your entire content set. However, as the amount of content that is authored in DITA grows, and as more teams specialize DITA to meet their authoring needs, the amount of content that you share and the manner in which you share it changes and grows.
To learn more about implementing DITA at your company, book a consulting session with DITA expert, Amber Swope.
