Presented by Mysti Berry, and reviewed by Frank Welsch
What emerging benefits are there in smartly structured technical documentation authored in a robust tool like DITA? Mysti Berry, veteran STC presenter and principal technical writer at Salesforce, brought attention to one such area at the April chapter meeting.
Berry first explained that in her presentation API-enabled content means a library of granular information chunks with consistent internal structure such that a machine could automatically capture relevant content for a new delivery channel. A successful reuse strategy generally entails smartly crafted standalone topics, which are complementary to one another and non-redundant. A gifted information architect who knows the authoring tool helps by sharing with all writers a well-defined subject schema (often referred to as the highfalutin-sounding taxonomy). If the source files adhere to a sharp taxonomy, so much easier it is for the documentation team to apply the metadata attributes and content references on the library for “API-ification.” For example, the API layer can grab a collection of topics that is appropriate for a desktop screen, a separate (perhaps smaller) collection for a tablet, and maybe just a single topic for a smart phone–all without human intervention.
Social Media and Content Strategy
Nowadays the most talked-about delivery channel is mobile technology. But what is driving the attitude of “Just tell me what I need to know” is not mobile devices per se. Instead, the demand is from growing numbers of users who do not want to navigate through a linear narrative. The growth of customizable devices and social media has created the expectation of a personalized experience.
Berry spoke of noted content strategist Karen McGrane as a visionary in the field of automated reuse. Search the web with keywords “NPR” and “McGrane,” and you will find numerous web sites that discuss how NPR is a pioneer in this area. However, Berry noted that most organizations have not yet reached the day when content reuse is fully automated. Rather, more realistically, she presented ideas on how to prime documentation for the time in the future when industry standardization will enable an API layer to reach all output devices.
Expend Resources to Maximize the Business Return-on-Investment
Automated smart reuse requires less actual writing. Technical communicators are freed to concentrate on crafting polished documentation and are less worried about the production and overhead of disparate information deliverables. Berry noted that this paradigm shift fosters the innate curator role of the technical writer.
By bringing your content outside “an HTML silo,” technical communicators can provide product information to prospective customers and reduce the resources required for sales support information deliverables. Berry posited that customers are not accustomed to automated content integration, which could give the company an opportunity to sell what the customer perceives as a customized information experience.
The value-add aspect of technical communicators could be summed up in the tagline that Berry has under her email signature: “Principal Technical Writer . . . we do so much more than write.”
How Do We Do It?
Berry shared a lot of practical advice about her experience working at Salesforce. In some cases, she had empirical findings about user behavior to back up her claims. For example, she and her colleagues have observed that users who do not find the information they need in a topic generally do not click on any links to related documentation that appears in the topic. Instead, if a topic does not have the answer, users are more likely to abandon the documentation altogether or start a search on key terms. While the tips she shared involved DITA as the authoring tool, many principles could probably be transferred to companies that use other authoring platforms.
Avoid excessive metadata tagging on the file level. Imagine 30 values times 10 different qualities, along with the overhead of filtering these metadata. This is a lot of work. It is also messy work to go into each topic to change metadata or to add and remove values as your library evolves. Consider instead grouping metadata by tagging chunks of topicref links in .DITAMAP files. (For DITA novices, picture this as roughly assigning tags and values to a virtual table of contents so that relevant content appears in the corresponding contexts.)
Minimize inline xref linking. A topic that contains a list of xref elements is probably not optimal usage of DITA. Manual work is required when the target topics disappear or change. The maintenance files for reusable text strings and content filtering, such as the content references file and .DITAVAL files, should be designed to autogenerate topics or a list within a topic that pertains to the user context. With manual links, the documentation team becomes less vigilant about “conditionalizing” the information. For example, an embedded xref link to a topic about a specific product feature that is not available in all versions of the product may readily slip past the writer’s attention.
Point the user back to the UI if possible. Be sure not to repeat what the user interface already tells or shows the customer (embedded assistance). (And let’s hope that the UI developers have been receptive to input about embedded assistance from technical writers!) If a single topic cannot contain everything that you need to tell the user, it is most effective to steer the customer back to the UI if the path of action or associated knowledge base can be gleaned there.
Use a content reference for reused text strings that do not warrant topic files. Short blurbs such as “Select x > y > z to open the abc window” can be set up as reusable text that can be invoked by a conref link.
Find out how customers really use the content and what they think of it. It’s easy to get hung up with the opinions of your colleagues. Technical communicators need to engage with the customers to get a reality check. Berry shared an interesting anecdote. At Salesforce, the technical writing team has on occasion deliberately published a poorly written topic to elicit comments and suggestions from the customers!