According to “The Good Fight,” a book by historian Stephen E. Ambrose, American factories produced 89,000 tanks, 300,000 military aircraft, seven million rifles, three million machine guns, and more than 650,000 Jeeps during World War II.
This makes one wonder: were there enough subject matter experts to write the technical documentation for all this equipment? And if not, who was responsible?
The world of content writing is constantly evolving. In recent years, we have seen a big shift in the role of SMEs. This shift was due to the birth of technical writers. Now, the two work together to ensure the creation and delivery of relevant content readable and understandable by all.
History of the SME
The SME, also known as the “subject matter expert” is a key player in the technical documentation writing process. This hasn’t always been the case. Back when technical documentation could best be characterized as a “cottage industry,” manuals were typically created as one-offs; written by experts, for experts. An increased demand for consumer products and military equipment like artillery, vehicles, and medical supplies during WWII sparked the need for technical writers—someone had to write the technical documentation so it was readable by everyone.
In addition, the first technical writing instructors were English professors in the US teaching courses to engineering students on how to clearly document their inventions. In part, this was done to encourage literacy among engineers, but also because engineers needed to better understand the increasingly non-engineering audiences they were writing for.
These events led to a discernible shift in the role of the SME.
SME Authoring and Technical Writers
To tackle this question, we first need to define what it means to be a technical writer. Technical writers are not SMEs but professional writers whose tasks involve gathering information, rewriting it in a way that is understandable by all, and delivering it through a well-defined medium. Technical writers interview SMEs about the topics in question, and determine what information is relevant and needs to be included, and what isn’t.
Nowadays, the advent of Agile documentation processes in small software development teams means that, in some circumstances, SMEs must write content. Now, with solutions like MadCap IXIA CCMS—which allow SMEs to review and edit documents—this phenomenon is becoming more common.
In the past five years, there has been an overall downward trend for technical writer job listings in the US. Conversely, there was an increase in jobs with titles like: content strategist, information architect, technical content specialist, information developer, DITA information architect, etc.
This means that technical writers are slowly losing their place as the primary redactors of technical documentation. Instead, they are taking on more of an editorial role. This concept is elucidated in the following passage by Tom Johnson in Technical Writing Trends for 2018:
“I think more engineers and other specialists will be writing docs. Because the information is so technical and specialized, tech writers will have a hard time developing the content. Instead, tech writers might play more specialized roles in editing, publishing, and curating content. Besides providing value in publishing, how exactly will generalists provide value in a world of increasing specialization?”
Building on Tom Johnson’s note, how can we prevent the risk of technical writers becoming those who simply “make the documentation look pretty?”
A possible answer is that technical writers will add more value by focusing on the content experience for users. One way this can be accomplished is by structuring the content using DITA:
- Multi-channel publishing
- Content reuse = content consistency
- Lower localization costs
- Bite-sized content easier for users to digest
DITA offers a revolutionary way for SMEs and technical writers to review and edit documents. Typed topics provide a structured focus for writing content (concept, task, reference, troubleshooting). Instead of reviewing an entire manual or chapter, review can be done at the topic level. When used within a CCMS, workflow ensures one or more SMEs approve of a topic before it goes out the door. Many companies have already adopted this approach, particularly in areas where verification is key, like in the medical device sector.
Technical Documentation Writing: Next Steps
Getting SMEs to learn DITA could generate some resistance. They may perceive learning structured authoring as an impediment to “simply getting the work done” and prefer to work with standards they are already familiar with, such as Markdown.
It is no secret that SMEs and technical writers need to find a certain harmony in their work together to be able to deliver high-quality content. Authoring in DITA can be a heavy and complicated process. This is an issue long-recognized by major DITA editor vendors.
With new developments in the industry, like MadCap IXIA CCMS 5.0, SMEs can contribute directly to creating, editing, and reviewing content—on any device. MadCap IXIA CCMS offers a solution for both players, rendering the technical documentation workflow more accurate and efficient. This product is designed with the lite user in mind, and is based wholly on DITA, though with all of its complexity hidden. In other terms, lite users are being given the flexibility to:
- Create a map
- Create a topic
- Edit a map (only important elements displayed for SMEs when editing a map)
- Move an object
MadCap IXIA CCMS Features Your SMEs Will Love
There are several features of MadCap IXIA CCMS that enable SMEs and other “lite users” to easily create, edit, and review content. There are three main views within MadCap IXIA CCMS Web that the lite user—most typically a SME—might use when creating and editing content:
- My Assignments
- Working with Topics
- Collaborative Review
Let’s explore each view:
My Assignments
The My Assignments view is like a homepage or staging area for the SME. Here, the SME is given a list of topics and possibly maps (depending on their access privileges) to work on. The SME only sees the content they have been assigned to edit and review. As they finish with their work on the content, the list of available topics will shorten (unless other topics have been assigned to them to review in the meantime). There is also a column that highlights when certain topics are due, providing a handy reminder of what content has the highest priority.
The MadCap IXIA CCMS My Assignments page provides an easy-to-navigate interface which helps users stay organized by displaying only the content they need to focus on and work with.
Working with Topics
Here we see the topic view within CCMS Web. In this scenario, a SME is looking at a sample topic that has been assigned to them to review. This view offers several new features like the breadcrumb, which shows you where you are in the document hierarchy, and oXygen web component; a robust, DITA-aware editing tool that comes bundled with this product.
The Details section to the right provides more info on the topic, including who assigned it, when it was last worked on, and who last made changes. In the main body of the webpage is the actual topic for the SME to work on.
As anyone who knows DITA can tell, this is a task topic. Despite the complexity of tags being used here, it is all “under the hood.” None of the complexity of DITA is present— instead what you get is a Word-like interface.
To save their work and send it to the server, the SME must simply click on the Check In button to the top-right. After having reviewed the topic and submitted their changes, the SME can now choose to either click the Move button to progress this topic to the next stage in the workflow or continue to edit the topic by clicking the Edit button.
After clicking the Move button, the SME can now choose to change the Status of topic. In a typical workflow it will have been set to “Work,” and would now change to “Next: review.” They also get to pick who (from a pre-populated drop-down list of valid reviewers) gets to look at it and work on it next. Once done, the SME clicks the Move button.
This brings us back to the My Assignments view, and the topic we worked on, called “Log in to the Acme interface” is now gone, having been moved to the My Assignments view of the person we chose in the previous step.
Collaborative Review
Collaborative Review allows more than one SME to comment on topics at the same time. In this case the SMEs are not actually editing the topics but are commenting on them. In Collaborative Review you don’t directly edit the content, instead you comment (or “annotate”) what’s there. This way, the SME can go through the content they have been asked to review, and comment on anything they think needs to be changed or added.
There is no “save” process for the whole page—each comment is saved incrementally within the Collaborative Review, and other reviewers can view (and potentially review) the SME’s comments. When the SME is done, all they must do is click the logo at the top-left which returns them to the My Assignments screen. They then can click Move which then routes the comments to a technical writer who can then incorporate those comments effectively.
In Summary
To conclude, with new developments in the industry like MadCap IXIA CCMS 5.0, SMEs can contribute directly to creating, editing, and reviewing content—on any device. Technical writers are able to concentrate on what they do best: communicate to users and become more effective mediators for providing information. MadCap IXIA CCMS offers a solution for both players, rendering the technical documentation workflow more accurate and efficient.
