Technical Writing: Structured authoring and WYSIWYG

Categories: Techwriter

There are dozens of platforms, software, and tools used in technical writing and one of the interesting things about the industry is that clients and companies typically have their own unique workflow when it comes to documentation. It's extremely difficult to say X is the standard and Y isn't. In general, however, the methods in creating technical documents fall into either structured authoring via XML (or a different markup language) or using a traditional WYSIWYG approach of writing and laying out documents. Personally, I agree wholeheartedly with the idea that the future of technical writing lies in structured authoring, but have often found myself working via WYSIWYG in a substantial amount of technical projects.

Advantages of structured authoring

1. After you learn the markup language, you just write and write and write without worrying about formatting, editing, sourcing, and rearranging text. XML properties allow writers to manage content easily without worrying about concerns such as line and paragraph spacing, fonts, and page layout - XSLT and templates created by the department specifically for the content will do that for you, maintaining the consistency of the output and eventual product.

2. It's said over and over but it is true - writing using XML allows technical writers to focus on everything from grammar to organization and accuracy because writers won't have to worry about threading text blocks, before and after spaces, tabs, and so forth.

3. Repurpose content easily. It's easy to repurpose content. Unlike WYSIWYG, which typically forces writers to literally copy and paste images and text from one document layout to another one, DITA and Docbook's XML structure allows a well-written set of XML files to be managed easily and exported to various formats such as HTML, PDF, DjVU, LaTeX, CHM, and RTF without much effort. Moreover, an organization's content management system maintains not only the validity of the written work, but its timeliness.

4. Flexibility. XML-based authoring allows writers to make use of many more formats seamlessly. In general, the ability to transform and fit into various environments makes structured authoring ideal for today's web-based world.

5. Technical writing is a presentation medium so the structure of information is extremely important especially for text dealing with scholarly subjects and in-depth engineering and science industries. Structured authoring forces a writer to maintain an organized approach when writing because of the nature of XML.

Advantages of WYSIWYG

1. WYSIWYG rules when it comes to images, callouts, and complex graphics. If the images do not come with callouts, then WYSIWYG applications are the way to go because most of them, such as InDesign and CorelDraw, include special tools for adding callouts and captions.

2. Images and editing with other applications is smooth and easy. Graphics intensive technical documents work better with a WYSIWYG family of authoring environments because of the seamless integration between image editor and page layout. Even the obsolete Adobe PageMaker had a fairly easy way of allowing the writer to launch an image editor from the document and link images. Some professionals are extremely dependent on Adobe Creative Suite's ability to work together as one.

3. Color and Printing Information. If the document is eventually going to be sent to the printing press and requires additional information such as color profiles and marks, WYSIWYG applications always include the option to add printer information with the document.

4. WYSIWYG software is easier to learn. Even with all the tools in InDesign and popular word processing software such as Microsoft Word and Corel WordPerfect, it's still faster to learn them compared to learning how to write with DITA or DocBook.

5. Technical writing, as mentioned before, is a presentation medium. WYSIWYG also works because the writer is able to have visual control over text layout and handling, visual cues, how the text is arranged in relation to the images, and how it catches/maintains your eye. This alone is an art (just visit Smashing Magazine) and a skill and involves everything from typography to design.

A combination of both WYSIWYG and structured authoring, such as the approach provided by Adobe FrameMaker, sounds ideal, but isn't always available in technical writing jobs or tasks. Moreover, it may add even further difficulty in the process if the application has its own way of handling content, as in the example of the aforementioned Adobe FrameMaker, which has its own extremely steep learning curve.

Personally, I'm a huge fan of structured authoring but understand why some companies still prefer the somewhat traditional WYSIWYG approach. In the "Post-PC" era, where the majority of documents and content is consumed via mobile devices like tablets and smartphones, it's clear that structured authoring and WYSIWYG writing won't disappear though it may be somewhat overshadowed by more interactive platforms, as evidenced by applications such as Apple iBooks Author. One can argue, however, interactivity should have long supplanted the somewhat more static approach of using DITA, DocBook, and desktop publishing with Adobe Flash and Adobe Captivate running around in the creative and corporate industry for years (though the aforementioned products are no longer as popular as before).

In the meantime, learning both approaches and understanding its relationship with HTML5 can go a long way in developing your skills as a technical writer prepared for different media.