At one time or another, I suspect that most programmers and technical
writers have attempted to “fix” technical writing in one way or
another. It’s a big problem space:
- Everything, or at least many things, need to be documented, because
undocumented features and behaviors cause problems that *one really
ought not need to review the source code and understand the
engineering to fix (potentially) trivial problems, every time the
occur.
- The people who write code are both not suited to the task of writing
documentation because writing code and writing documentation are in
fact different skills. Also, I think the division of labor makes some
sense here.
- Documentation, like code, requires maintenance, review, and ongoing
quality control, as the technology and practice change. That’s a lot
of work and particularly for large projects, that can be a rather
intensive task.
- Lots of different kinds of documentation are needed, and depending on
the specific needs of the user, a basic “unit of documentation,” may
need to be presented in a number of different ways. There are a number
of ways to implement these various versions and iterations, but they
all come with various levels of complexity and maintenance
requirements.
The obvious thing to do, if you’re a programmer, is to write some
system that “solves technical writing.” This can take the form of a
tool for programmers that encourages them to write the documentation
as the write the code, or it can take the form of a tool that enforces
a great deal of structure for technical writing, to make it “easier”
for writers and programmers to get good documentation. Basically “code
your way out” of needing technical writers.
You can probably guess how I feel about this kind of approach.
There is definitely a space for tooling that can make the work of
technical writing easier, as well as space for tools that make the
presentation of documentation clearer and more valuable for users. Tools
won’t be able to make developers to write, at least not without a
serious productivity hit, nor will tools decrease the need for useful
documentation.
It’s a difficult problem domain. While there is a lot of room for
building programs that make it easier to write better documentation, the
problem is that the temptation to write too much software is great.
Often the problems in the technical writing process, including high
barriers to entry, complicated build/publication systems, and difficult
to master organizational methods, which are easy to address in programs.
Meanwhile, most of these issues can be traced to overly complex build
tools and human-centered problems, which are harder to address in code.
And since documentation takes the form of simple text, which seems easy
to deal with, developers frustrated by documentation requirements, or
technical writing teams, are prone to trying to write something to fix
the apparent problem.
Which brings us to the present, where, if you want to write and publish
documentation, your choices are:
- Use a wiki, which isn’t
documentation
but the software generally does a good job of publishing content, and
wiki engines mostly don’t have arcane structures of their own that
might get in the technical writer’s way. Downside: it’s the
wrong tool for the job and it forces writers and editors to maintain
style themselves across an entire corpus, which is difficult and
eventually counterproductive.
- Use some other existing content management system. Typically these
aren’t meant for documentation, they have difficult to use
interfaces, because they’re meant to power websites and blogs, and
they almost impose some sort of structure (like a blog,) which isn’t
ideal for conveying documentation.
- Use an XML-based documentation tool-set. This is probably the best
option around, at the moment, as these tools were built for the
purpose of creating documentation. The main problems are: they’re not
particularly well suited for generating content for the web (which I
think is essential these days) and as near as I can tell they make
humans edit XML by hand which I think is always a bad idea.
- Build your own system from the ground up. Remember text is easy to
munge and most of the other options are undesirable. Downside:
homegrown projects take a lot of time, they’re always a bit more
complex than anyone (except the technical writers?) expect, and it’s
easy to almost finish and that’s bad because half-baked
documentation systems are most of what get us into this problem in the
first place.
So it’s a thorny problem and one that lots of people have (and are!)
trying to solve. I’ve been watching a tool called
dexy for the last few weeks (months?) and I’ve been
very interested in it’s development and the impact that it, and similar
tools, might have on my day-to-day work. This post seems to be the first
in a series of thoughts about the tools that support technical writing
and documentation.