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

Adobe TCS3 is here with new XML and Social Media features!

© 2011 Ugur Akinci I’m excited to hear that Adobe’s Technical Communication Suite 3 is introduced with exciting built-in DITA/XML and social media/networking features. I understand both FrameMaker 10 and Robohelp 9 are being shipped as we speak. Here is a great intro by Adobe Senior Product Evangelist RJ Jacquez. It looks like this version…

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