Write tech docs in plain text
...and don't use word processors

One of mankinds most complex invention has been - and will be - described in plain text format: The Internet. If plain text is good enough for HTTP, it should be good enough for your next project's technical documentation.

As a software developer I deal with plain text (source code) all day long. I'm used to it and I like it. So why not use it for technical writing, too?
In my experience plain text can give you a pretty large number of advantages over word processors:

  • It's distraction-free. You just write, you don't feel the force to prettify everything as-you-type. Working with plain text is about "write now, prettify later".
  • It's scalable. Ever tried to work on Word documents with, say, more than a hundred pages? Or master/detail documents? Oh my. With plain text you split up your work in as many files as you want and hyper-link them together in any way you want. Or, you just keep one file. The NFS protocol specification is exactly one document with over 600 pages.
  • It's durable. There are ascii documents from the sixties. You can still read them.
  • It's processable. With plain text files, nothing can stop you from programmatically processing the content. Need the line count? wc -l. Need to find every occurence of "Foobar"? find -name "*.txt" | xargs grep Foobar. Need to change Peter to Paul? sed s/Peter/Paul/. In whatever way you want to process your written content, plain text lets you automate the heck out of it.
  • It's versionable. Put your documents under version control (git, svn, source safe, whatever..) and diffing your contents comes for free. Need to find the difference between two versions? git diff 186d066 e1e9c5c. You can even have a graphical representation of the changes along with the names of the users who made the changes. Try that with MS Word or Google Docs. For small documents with only a few revisions: Maybe. For large documents with many revisions: No way.

To be fair, plain text comes with drawbacks, too:

  • It does have no images. A picture says more than a thousand words, they say. Well, for developers it might not be all that true. After all we program by typing plain text and not by drawing images (altough this is what they told us in the 90ies). But real people want images. With plain text all we can do is ASCII art or embedding images generated with non-plain-text programs.
  • It's not consumable by real people. Real people (customers, managers, non-technicall people in general) normally want to read pretty-printed documents with pretty font styles, footnotes, side-comments, auto-generated page numbers, colored texts, and whatnot. Well, if we use proper markup languages (e.g. html, markdown) we can generate pretty nice outputs. But it comes at a cost. And if it's not in the markup it's hard to add later. E.g. markdown does not know anything about colors or stylesheets.
  • It's not WYSIWYG. Real people are used to get what they see instantly. In the typical non-technial world, a large amount of time is spent on the looks of a document, not on its content.

To summarize, I think it depends on what tool gets the job done: Plain text has its advantages, and for technical writing I tend to favour it over word processors. But for communicating with non-technical people I think WYSIWIG is better suited.