Technical Writing for Geeks
I worked in the tech writing field for many years. A little freelance but mostly with in-house procedure writing. Cornerstone tools found in the technical writing business are FrameMaker and Microsoft Word.
Since I started using free/libre software more than 13 years ago I have been watchful for conversations about tech writing in free/libre software. Sadly, often free/libre enthusiasts boast how they do not use word processors to write and instead use typesetting tools.
Latex being the usual darling. Throw in the various markup and markdown languages.
How good are these tools? I do not know, but have you ever noticed in many free/libre documents how headings often are left dangling at the bottom of a page rather than moving to the next page to remain with the child paragraph? Easily resolved in any word processor using a Keep With Next attribute.
This boastful approach tends to be more about geek creds than inviting people to write. When the tool chain is designed by geeks for geeks, only geeks will volunteer. When only geeks are writing, the only perspective will be that of a geek. Thus a continual cry in free/libre software circles about poor documentation and the lack of documentation.
This “geek cred” approach will not attract non technical users who might otherwise volunteer to help write documentation. Non technical users are not going down this road. Non technical users do not care about geek creds. With respect to computers, non technical users are pragmatists. The computer is a tool and nothing more.
More people might help if they are offered a traditional and familiar writing tool. Go ahead, shudder. Yes, that means a word processor. Or something similar.
Point-clicky.
LibreOffice Writer should be a prime candidate for this kind of work. LibreOffice Writer has many elements of both FrameMaker and Word.
Yes, I hear the groans. Coming only from geeks.
The only text interface the majority of people are familiar is Microsoft Word. Many of these people are not even aware of Notepad.
Laugh all you want. This is the reality. This is not about emacs vs. vi. This is not about reStructuredText vs. Markdown. This is not about wiki markup languages. This is not about the latest text editor craze. Or about LaTex. This is about pushing aside geek creds. The geek challenge is helping non technical people use a familiar interface to write documentation.
Even the folks at MediaWiki recognize the challenge of expecting non technical users to learn a markup language.
Despite all the alleged bravado otherwise, word processors are powerful writing tools. The key is understanding templates and style tags.
Every time somebody boasts about not using such tools, I suspect the person likely has no appreciation for style tags in a word processor. Style tags are a staple in the professional technical writing business. Style tags are part of structured writing.
While a majority of people using word processors do not understand templates and tags, if they get to use a familiar writing and editing environment they will learn. Throw them into a geek environment for writing and they will run.
Needed here is a LibreOffice Writer template containing appropriate style tags. The style tags names would be the same as is in Docbook or reStructuredText. The tags would work the same as in any outline: paragraph tags with common names such as heading, subheading, body text, warning, note, etc. Character tags such as code, command, date, emphasis, etc. With such a template writers do not focus on formatting documents. They focus solely on writing structurally. The tags provide nominal on-screen formatting support only to help the writer visualize the structure of the document. Final output formatting information is not needed in the tags. Final formatting is the territory of backend processors.
Just about everyone with any kind of reasonable education knows how to use an outline as a writing tool. Fundamentally, that is structured writing in a nutshell.
The style tags help writers see the outline. They get to focus on writing content.
FrameMaker is a common tool in the tech writing field. An expensive piece of proprietary software. People pay for this extravagance because the software is designed to help writers focus on content rather than formatting. The focus today in FrameMaker is with formal structured content management environments such as DITA.
While very much a proprietary tool designed with vendor lock-in in mind, FrameMaker is a tool free/libre developers could observe and notice.
Structured text — outlining — is the basis of all technical writing. FrameMaker has been providing this environment for 35 years. Without knowledge of markup or markdown. Just templates and style tags. Yet if desired, FrameMaker supports exporting files in a FrameMaker Markup file (MIF), which looks like any other Standard Generalized Markup Language (SGML) file.
Sound familiar?
There is no reason LibreOffice Writer cannot be used in the same role. In the early days of OpenOffice there once was a DocBook template. That template faded into the sunset like a cowboy and horse in a 1950s movie.
LibreOffice stores files in XML. The well vaunted XML container. XML, like HTML, is a subset of SGML, and was intended from the beginning to be portable, to be — eXtensible. Adept programmers should be able to parse LibreOffice Writer XML output as needed for various backend processors for HTML, PDF, and ePub. Because the style tag names would match expected backend tag names, parsing should be a straightforward programming project.
Perhaps new LibreOffice export add-ons could be developed to save the documents in the desired backend processing format. Or perhaps something like Pandoc.
An example of such an approach is the LibreOffice extension to support MediaWiki. Writers using this extension do not need to learn or deal with MediaWiki markup.
Unlike traditional What You See Is What You Get (WYSIWYG), this approach is What You See Is What You Mean (WYSIWYM). A well known tool that uses the WYSIWYM is Lyx, a front-end wrapper to LaTex.
Perhaps a skilled programmer could add additional export plugins to Lyx. Or for those who do not want to install LibreOffice, some similar export filters for Abiword.
When writers grasp they are writing based on an outline, when they grasp they are not required to fiddle with formatting, when they realize they do not have to learn geek tool chains, they will be in a safe comfort zone and more willing to help.
This is not a wild dream. In a past life in a galaxy far away I developed procedure writing systems. One for WordPerfect for DOS, another for MS Word 6, another for Word 97, and again in FrameMaker. The basic foundation was always the same: templates and style tags. Toolbars were redesigned so writers could not manually format text and had to use the tags. The result was consistency.
The customers of these systems did not need support for multiple output formats and could live with single proprietary file formats. XML allows going beyond that limitation with HTML, PDF, and ePub.
Writers want to write. They do not want to learn “tool chains.” Volunteers want to become involved. Outside of geekdom most people abhor learning anything more about computers than is necessary. To them the computer is a tool and only a tool.
Free/libre developers can rise to the occasion. Provide the tools needed to encourage people to help with documentation. Let the geeks be geeks and help the non technical contributors feel safe.
Current tool chains keep the door closed. A nice thing about a simple word processor approach is volunteers do not need to learn exotic tool chains or software. Just learn a few style tags and write.
Posted: Category: Usability Tagged: General, Tech Writing
Next: Skill of the Craft
Previous: Simple Proofreading Techniques