pages tagged writingyakkinghttp://yakking.branchable.com/tags/writing/yakkingikiwiki2016-06-29T11:39:11ZWriting documentationhttp://yakking.branchable.com/posts/writing/Lars Wirzenius2016-06-29T11:39:11Z2016-06-29T11:00:06Z
<p>You know what it's like to not understand how some silly software
needs to be used. Ideally, it should be obvious, but in practice,
you'll want to read at least some documentation, if only to have some
general understanding of what the software is for.</p>
<p>Sometimes you yourself will have to write documentation or other prose
about your software. It might not be user-oriented documentation; it
might be a project proposal, an architecture overview, or an incident
report on how you dealt with a security problem in the code.</p>
<p>All hackers (programmers, software developers, system administrators)
need to write prose. It's inevitable, so it makes sense to learn how
to do it without too much pain. This article gives a brief
introduction to the topic, from the assumption that you're a programmer.</p>
<hr />
<p>You're a programmer. You should probably approach writing as you would
programming.</p>
<h1>Overview of documentation development</h1>
<p>Although all the details are different, writing as a process can be
similar to programming.</p>
<ol>
<li>Define acceptance criteria and scope.</li>
<li>Specify relevant user personas and use cases.</li>
<li>Write a prototype document.</li>
<li>Get your text reviewed and user-tested.</li>
<li>Make changes based on review feedback.</li>
<li>Iterate until good enough.</li>
</ol>
<h1>Acceptance criteria and scope</h1>
<p>You should decide what your document is for. What should it cover?
What does it not need to cover? When is the document good enough that
you can stop writing it?</p>
<p>These are similar to the question you'd decide on when writing some
software. The difference between a writer and a programmer is that the
writer finds it easier to answer these questions about a document and
a programmer about software.</p>
<p>As an example, this blog post itself is meant to cover basics of
writing documentation. It won't go into a deep discussion into
tooling. It's done when I think it's going to be useful to read by
someone who dreads writing any prose at all.</p>
<h1>User personas and use cases</h1>
<p>Just as for software, documentation has target users. In writing, this
is often expressed as "target audience". Who are the people you want
to read the documentation? The sullen answer of "don't know, don't
care, don't wanna, not gonna" isn't useful here. If you really aren't
going to write anything, then you can stop reading. If you really are
going to write, you need at least a rudimentary answer.</p>
<p>In addition, use cases can also be relevant for documentation. For
example, a manual for a program might have use cases such as "how to
start the program", "how to configure the program", and "what does
this error message mean?".</p>
<h1>A prototype document</h1>
<p>A software prototype is a rough sketch of what the program might do
when it's finished. The first prototype document should be an outline,
perhaps with a paragraph of text for each chapter or section. When
someone reads it, they get an idea of what the finished document will
be like.</p>
<p>Later document prototypes will add more text. There might be many
iterations, and each might fill in a chapter or two.</p>
<h1>Get your text reviewed and user-tested</h1>
<p>Code review is quite efficient at finding problems. Text review is
even more efficient. User-testing is also useful for documentation:
you get people to read your text and ask them questions to see if they
understood things correctly.</p>
<p>If you do many iterations, you'll want to find new readers every now
and then. Fresh eyes are better.</p>
<h1>Make changes based on review feedback</h1>
<p>This is a no-brainer.</p>
<p>Actually, no, it isn't. Sometimes feedback is ambiguous, or different
people give conflicting feedback. Or they're utterly, totally wrong
about semicolons; they're not the evil of our times, after all.</p>
<p>You do your best. The next iteration will show if you made things
better or not.</p>
<p>Sometimes feedback is soul-crushing. People may say unpleasant things
about the thing you've spent days or weeks or months to make. Same
thing happens with code, of course. If you can, try to see if they
have a kernel of useful truth that you can extract and make use of,
but otherwise just ignore those people in the future.</p>
<h1>Iterate until good enough.</h1>
<p>With code, iteration is fairly straightforward. With text, you
probably want to iterate fewer times to avoid exhausting your readers.</p>
<p>However, you should always feel free to treat each iteration as a
draft, with the intention of making the next one better than the
current one.</p>
<h1>Random points about writing</h1>
<p>Writing text is much less painful if you are good at typing. Touch
typing really helps. It helps with code as well, but not nearly as
much.</p>
<p>It may help you to use your usual tools: your text editor, version
control system, etc, instead of a WYSIWYG word processor. Familiarity
helps, and it helps not getting angry at all the ways in which modern
word processors get in your way by trying to be helpful. I'm being
opinionated here: if you like using a word processor, by all means do.</p>
<p>Don't worry about layout, typography, pagination, etc. Don't even
worry about length, since you're writing digital content, and are not
bound by limitations of the physical world. Instead, worry about the
structure of your document.</p>
<p>Don't worry about writing perfect prose. It's useful to use a spelling
checker, but you can do that after you've got the text done otherwise.
Don't worry about using fine or fancy language, as you might find in
some world-class literature; it's perfectly OK, and often preferably,
to only write simple sentences.</p>
<p>You're writing software documentation. Don't worry about style, unless
you want to. ABC is the goal: accuracy, brevity, and clarity. You can
add humour, if you want to, but that's a <strike>squirrel</strike>, sorry, personal
choice. Completely optional. If you're overcoming a reluctance to
write, it's important that you write, not that you entertain.</p>
<p>You may benefit from the <a href="http://www.williamlanday.com/2013/02/06/age-of-distraction/">Cory Doctorow Method</a> of writing. After
you have an outline, write a draft of one section. If your sections
are of reasonably small scope, it might take you half an hour per
section, which you can do in one sitting. Repeat every day, and in
what feels like no time at all, you'll have a big manual.</p>