Implementing Structured Authoring

Imagine that every day you see dozens of mismatched PDFs that are produced and uploaded to some documentation site that doesn’t have navigation. Fellow tech writers are wasting loads of valuable hours fixing one thing across masses of documents when they could be creating new content instead. Seems like it’s the place to implement structure. Let’s discuss structured authoring and how to implement it for your benefit. It can be hard and time-consuming, but the quality, consistency, searchability, and overall flexibility of a structured environment will be well worth it. And don’t forget about translations – when you start translating, you’ll save tons of money.

What is Structured Authoring?

Every technical writer knows such a concept as “structured authoring.”

Structured authoring is a workflow for technical documentation where the content is controlled by certain rules.

It is the foundation for an automated publishing process. The structure facilitates content control, management, and conversion into different formats and ensures the consistency of the underlying code of your content. In structured authoring, a predefined information model describes the content structure and provides a limited set of elements that can be used in a text. Structured content is written in an XML markup language.

Switching to Structured Authoring

Whether you are migrating from MS Word or Unstructured FrameMaker, you encounter the wide world of XML – a simple text-based format for representing structured information. Before changing anything in your content, you must consider the content strategy to understand what you need and how you get there. The content must be:

• In a useful form;
• Feasible and accurate;
• Written to suit its function so that it can be easily used and repurposed.

What Happens After You Move Your Content to Structured Authoring?

1. Centralized style management. XML completely separates the raw content from the output styling. Before publishing, the content is authored in unformatted XML. This freedom from inline styling allows you to focus on the content and send the same content through multiple stylesheets to create multiple outputs (PDF, HTML, etc.).
2. Continuous text is divided into small meaningful fragments. During doctype configuration, you can determine the size of those fragments. When you make a change or author content in XML, you work with the smallest piece of XML. So instead of reading the full book or full chapter, you may read a section or subsection. Working in smaller pieces is easier on the authoring software and also enables shared authoring and content reuse.
3. You can now reuse your content. For example, you have 100 manuals in the company, all of them contain the same text fragment. One of the manuals is changed, you would only need to update that one file, and whenever you opened and published the 100 documents, they would all automatically pull the changes. Content reuse can be implemented at multiple levels. You can also create items or units to reuse all the way down to the phrase or word level.
4. Work together as one. Remember how you worked on your computer, apart from other writers and no one had access to your documents? XML changes this. These files are hosted on a server and checked in and out when edited by the authors. All authors can have access to the same content files and contribute to the same manual. With fragmented files, multiple authors can be working on the same document simultaneously. Content management prevents authors from creating conflicts within the files. Writers can share the work. XML encourages more collaborative working within your writing team.
5. You achieve consistency. The company style guide may say that a logo should only be used on a black or white background, or the text should be always aligned in the center of a text box. However, some writer decided that they prefer the text aligned to the left. With manual formatting, this writer can get away with this deviation…But this changes with XML. XML simply will not allow writers to author creatively. The doctype contains the schema that dictates which elements are permitted and where, and also the stylesheets that format the outputs. In XML, the writer could only place a text in designated locations, and the stylesheet renders it centered. There is still some flexibility in XML, but for the most part, it ensures the same content appears in the same locations styled in the same way. Authoring in XML will enforce consistency between all authors working in the doctype.

Who Shouldn’t Implement Structured Authoring?

Structured authoring is not the answer for all content development workflows. For some environments, implementing structure will be more trouble than it’s worth. Many writers who are new to a structure are uncomfortable with the perceived lack of control over the final document. The following are some examples where structure probably doesn’t make sense:

• Small sets of technical content. Companies with thousands of pages of content need to consider structure. Organizations with tens of thousands or more pages almost certainly need both structure and content management. An organization that only manages a hundred pages of content doesn’t need elaborate structure and content management. If you have thousands of topics, there is a point where the value of structure outweighs the implementation cost.
• Fiction and other creative writing. Fiction is unlikely to fit into a predefined structure, and it probably doesn’t require the type of reuse and management that technical content does.
• Low-value content. If you do not plan to reuse content, or if a document doesn’t contain sufficient information, the effort of structuring it is probably not worth it. Day-to-day business communications, such as email and memos, generally fall in this category. Be on the lookout, though, for higher-value content, such as complex proposals that could be reused.
• A company without the necessary expertise. A company should have an expert who would implement a complicated workflow. Without such an expert the implementation would be impossible.
• Writers that strive for simplicity. Some tech writers are against the need to make up DITA maps and write XML where the structure of topics changes greatly. They prefer using WYSIWYG.
• The impracticality of expenses. Sometimes, the expense of CCMS implementation outweighs the benefits realized, especially in smaller groups with a smaller amount of content.

An Alternative to Structured Authoring

As you saw from the above, the structured authoring is closely connected with the XML format, they are often used almost interchangeably. However, this format is not mundane for some people, so this may become an issue. Not every group of technical writers will make use of structured authoring and XML. At the same time, all tech writers would like to use the benefits it offers. So if you understand that you need a more consistent environment, but structure enforcement is a bit too much, there is an alternative – cloud-based documentation tool ClickHelp that has almost the same advantages together with the ease of use. See for yourself:

1. In ClickHelp, there are templates and quick parts that help authors get some ready parts quickly, but here it is a matter of convenience, not enforcement.
2. Content reuse is simple thanks to snippets and variables.
3. Single-sourcing helps make the documentation authoring process more efficient. With ClickHelp, you don’t need to write XML, just choose what elements should be placed into a certain output with the help of Output Tags.
4. For better consistency, you can manage the styles of tables, lists, etc. in a shared CSS style file applied in all your articles. A visual editor doesn’t require your understanding of XML. But in case you need to have low-level control over HTML code it allows you to get access to HTML source.
5. ClickHelp incorporates a lot of options for teamwork. It comprises convenient means of content collaboration. The team can work together over the same project on a single portal. For example, review workflow serves to get input from SMEs. So it is a unified environment for teams, not just an author tool.

Conclusion

Many businesses still function the same way they did a decade ago, emailing Word files and PDFs across teams to collect input and approvals. The demands of modern technical writing don’t match with long-established processes anymore. Businesses cannot operate the same way as before – especially when the amount of content they’re creating is growing swiftly. Companies that operate in regulated environments get the increased chances of exposure to risks and violation of compliance standards. To avoid such risks you can implement structured authoring or sign up and get your own ready-made portal in ClickHelp. Be progressive – get your free trial now!

Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices