How to Write Goal-Focused and Structured Technical Documents

PREMISE Most of the technical documentation that exists in the world today is feature-focused. It is also unstructured: there is no well-defined hierarchy between the components of the document. For example, there is no enforcement of a hierarchical rule like “every task description shall be followed by a reference section.” See this related article. PROBLEM…

Read More

Well Formed versus Valid XML Documents

“Well formed” (or “Well-formed”) and “Valid” are two very important concepts in structured XML authoring. Well Formed Well formed means, the XML tags used in the structured document follow a set of XML rules. Two of the more important rules are 1) tags should be paired with opening and closing tags, and, 2) tag pairs…

Read More

A Source of Potential Component Conflict when Multiple Authors Work in Structured Authoring Environment

Multiple authors writing “components” instead of “pages” is the future of technical communications (if not technical training and e-learning). When it comes to documentation, it really makes sense to “write once and publish multiple times”, as the saying goes. And that’s only possible if we all get used to writing “components” (sometimes also referred to…

Read More

Two Excellent Reasons Why You Should Learn XML

© 2010 Ugur Akinci There are two excellent reasons why you should learn XML as a technical communicator, both argued well by Jabin White at his seminal post “XML is Here to Say (I Promise)“. The first reason is: XML is platform and application independent. When you create an XML-tagged document, what you’re creating is…

Read More

Reusable Components in Structured Authoring

© Ugur Akinci It is useful to take an inventory of all the reusable components (text strings) in your technical documents as a prelude to structured authoring. Whether you use DocBook, DITA, or some other XML-based system, identifying the reusable components in your documents is an important prerequisite before you make the switch to XML-based…

Read More