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.