Subject: Matt Palmer: The Vicious Circle of Documentation

Date: Tue, 19 May 2015 19:24:19 +0200

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">
<html>
	<head>
		<meta http-equiv=3D3D3D3D3D3D3D"content-type" content=3D3D3D3D3D3D3D"text=
/htm=3D
l; c=3D3D
hars=3D3D3D
et=3D3D3D3D
=3D3D3D3D3D3D3DU=3D3D3D3D3D
TF-8" =3D3D3D3D3D3D
/>
		<link rel=3D3D3D3D3D3D3D"alternate" type=3D3D3D3D3D3D3D"application/rss+x=
ml" =3D
titl=3D3D
e=3D3D3D3D=3D3D3D
3D3D3D=3D3D3D3D
"RSS f=3D3D3D3D3D
eed" h=3D3D3D3D3D3D
ref=3D3D3D3D3D3D3D"http://www.hezmatt.org/~mpalmer/blog/rss.xml" />
		<link rel=3D3D3D3D3D3D3D"alternate" type=3D3D3D3D3D3D3D"application/atom+=
xml"=3D
 tit=3D3D
le=3D3D3D
=3D3D3D3D3D3D3=3D3D3D3D
D"Atom=3D3D3D3D3D
 feed"=3D3D3D3D3D3D
 href=3D3D3D3D3D3D3D"http://www.hezmatt.org/~mpalmer/blog/atom.xml" />
		<title>
			Brane Dump: The Vicious Circle of Documentation
		</title>
		<link rel=3D3D3D3D3D3D3D"stylesheet" type=3D3D3D3D3D3D3D"text/css" href=
=3D3D3D3=3D
D3D3D3=3D3D
D"http=3D3D3D
://www=3D3D3D3D
.hezma=3D3D3D3D3D
tt.org=3D3D3D3D3D3D
/~mpalmer/blog/stylesheet.css">
	</head>
	<body>
		<div id=3D3D3D3D3D3D3D"header">
			<h1>Brane Dump</h1>
			<p id=3D3D3D3D3D3D3D"subtitle">The thoughts of Matt Palmer</p>
		</div>
		<div id=3D3D3D3D3D3D3D"body">
			<div id=3D3D3D3D3D3D3D"sidebar">
				<ul>
					<li>
						<span class=3D3D3D3D3D3D3D"menuheading">
							BlogNav:
						</span>
					</li>
					<li>
						<a href=3D3D3D3D3D3D3D"http://www.hezmatt.org/~mpalmer/blog/archives.=
ht=3D
ml=3D3D
">
							Archive of all posts
						</a>
					</li>
				</ul>
			</div>
			<div id=3D3D3D3D3D3D3D"content">

				<h1 class=3D3D3D3D3D3D3D"post">
					<a href=3D3D3D3D3D3D3D"http://www.hezmatt.org/~mpalmer/blog/2015/02/15=
/t=3D
he=3D3D
-d=3D3D3D
oc=3D3D3D3D
um=3D3D3D3D3D
en=3D3D3D3D3D3D
tation-vicious-circle.html"
					   title=3D3D3D3D3D3D3D"The Vicious Circle of Documentation">
						The Vicious Circle of Documentation
					</a>
				</h1>
				<p class=3D3D3D3D3D3D3D"postsubhead">
					Posted: Sun, 15 February 2015
					| <a
					href=3D3D3D3D3D3D3D"http://www.hezmatt.org/~mpalmer/blog/2015/02/15/th=
e-=3D
do=3D3D
cu=3D3D3D
me=3D3D3D3D
nt=3D3D3D3D3D
at=3D3D3D3D3D3D
ion-vicious-circle.html">permalink</a>
					| <a
					href=3D3D3D3D3D3D3D"http://www.hezmatt.org/~mpalmer/blog/2015/02/15/th=
e-=3D
do=3D3D
cu=3D3D3D
me=3D3D3D3D
nt=3D3D3D3D3D
at=3D3D3D3D3D3D
ion-vicious-circle.html#comments">
					=3D3D3D3D3D3D09
							4 Comments
					=3D3D3D3D3D3D09
					</a>
				</p>
<p>Ever worked at a company (or on a codebase, or whatever) where it seemed
like, no matter what the question was, the answer was written down somewhere
you could easily find it?  Most people haven=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=
=3D3D3D=3D
3D3D3D=3D3D
99t, s=3D3D3D
adly, =3D3D3D3D
but th=3D3D3D3D3D
ey do =3D3D3D3D3D3D
exist,
and I can assure you that it is an absolute pleasure.</p>

<p>On the other hand, practically <em>everyone</em> has experienced complet=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
ely
undocumented systems and processes, where knowledge is shared by
word-of-mouth, or lost every time someone quits.</p>

<p>Why are there so many more undocumented systems than documented ones out
there, and how can we cause more well-documented systems to exist?  The
answer isn=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D99t =3D3D3D3D3D3DE2=3D=
3D3D3D3D3D=3D
80=3D3D3D3D3D3=3D3D
D9Cpeople ar=3D3D3D
e lazy=3D3D3D3D3D3DE=3D3D3D3D
2=3D3D3D3D3D3D80=3D3D3D3D3D3D9D, a=3D3D3D3D3D
nd the solution is=3D3D3D3D3D3D
 simple =3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D93 though not
easy.</p>

<h1 id=3D3D3D3D3D3D3D"why-johnny-doesnt-read">Why Johnny Doesn=3D3D3D3D3D3D=
E2=3D
=3D3D3D3D3=3D3D
D3D80=3D3D3D
=3D3D3D3D3D3D99=3D3D3D3D
t Read</=3D3D3D3D3D
h1>

<p>When someone needs to know something, they might go look for some
documentation, or they might ask someone else or just guess wildly.  The
behaviour =3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D9Clook for documentati=
on=3D3D3=3D
D3D3D3DE=3D3D
2=3D3D3D3D3D3D=3D3D3D
80=3D3D3D3D3D3D9D =3D3D3D3D
is often rei=3D3D3D3D3D
nforced nega=3D3D3D3D3D3D
tively, by the
result =3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D9Cdocumentation doesn=3D3=
D3D3D3D3=3D
DE2=3D3D3D3D=3D3D
3D3D80=3D3D3D3D3=3D3D3D
D3D99t exist=3D3D3D3D
=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D
=3D3D3D3D3D3D9D.</p>

<p>At the same time, the behaviours =3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D=
3D3D9C=3D
ask so=3D3D
meone=3D3D3D
=3D3D3D3D3D3DE2=3D3D3D3D
=3D3D3D3D3D3D80=3D3D3D3D3D3D=3D3D3D3D3D
9D and =3D3D3D3D3D3DE2=3D3D3D3D3D3D
=3D3D3D3D3D3D80=3D3D3D3D3D3D9Cguess wildly=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D=
3D3D3D3D3D=3D
9D are
positively reinforced, by the results =3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D=
3D3D3D=3D
9CI ge=3D3D
t my q=3D3D3D
uestio=3D3D3D3D
n answ=3D3D3D3D3D
ered=3D3D3D3D3D3D
=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D9D and/or
=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D9Cat least I can get on with my =
work=3D
=3D3D3D3D3D3=3D3D
DE2=3D3D3D3D3D=3D3D3D
3D80=3D3D3D3D3D3D9=3D3D3D3D
D.  Over tim=3D3D3D3D3D
e, people op=3D3D3D3D3D3D
timise their
behaviour by skipping the =3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D9Clook=
 for d=3D
ocumen=3D3D
tation=3D3D3D
=3D3D3D3D3D3DE=3D3D3D3D
2=3D3D3D3D3D3D80=3D3D3D3D3D
=3D3D3D3D3D3D9D step, an=3D3D3D3D3D3D
d just go
straight to asking other people (or guessing wildly).</p>

<h1 id=3D3D3D3D3D3D3D"why-johnny-doesnt-write">Why Johnny Doesn=3D3D3D3D3D3=
DE2=3D
=3D3D3D3D=3D3D
3D3D80=3D3D3D
=3D3D3D3D3D3D9=3D3D3D3D
9t Write=3D3D3D3D3D
</h1>

<p>When someone writes documentation, they=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D=
3D3D3D=3D
3D3D99=3D3D
re hop=3D3D3D
ing th=3D3D3D3D
at peo=3D3D3D3D3D
ple wi=3D3D3D3D3D3D
ll read it
and not have to ask them questions in order to be productive and do the
right thing.  Hence, the behaviour =3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3=
D3D9Cw=3D
rite d=3D3D
ocumen=3D3D3D
tation=3D3D3D3D
=3D3D3D3D3D3DE2=3D3D3D3D3D
=3D3D3D3D3D3D80=3D3D3D3D3D3D9D is=3D3D3D3D3D3D
 negatively
reinforced by the results =3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D9CI <e=
m>stil=3D
l</em>=3D3D
 get a=3D3D3D
sked q=3D3D3D3D
uestio=3D3D3D3D3D
ns=3D3D3D3D3D3DE2=3D3D3D3D3D3D
=3D3D3D3D3D3D80=3D3D3D3D3D3D9D, and =3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D=
3D3D9Cnobo=3D
dy does
things the right way around here, dammit!=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3=
D3D3D3=3D
D3D9D<=3D3D
/p>

<p>Worse, though, is that there is very little positive reinforcement for t=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
he
author: when someone <em>does</em> read the docs, and thus doesn=3D3D3D3D3D=
3D=3D
E2=3D3D
=3D3D3D
=3D3D3D3D3D3=3D3D3D3D
D80=3D3D3D3D3D
=3D3D3D3D3D3D99t =3D3D3D3D3D3D
ask a question,
the author almost certainly doesn=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3=
D99t k=3D
now th=3D3D
ey dod=3D3D3D
ged a =3D3D3D3D
bullet=3D3D3D3D3D
.  Sim=3D3D3D3D3D3D
ilarly,
when someone does things the right way, it=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D=
3D3D3D=3D
3D3D99=3D3D
s unli=3D3D3D
kely t=3D3D3D3D
hat an=3D3D3D3D3D
yone w=3D3D3D3D3D3D
ill
notice.  It=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D99s only the mistakes=
 that =3D
catch =3D3D
the at=3D3D3D
tentio=3D3D3D3D
n.</p>

<p>Given that the experience of writing documentation tends to skew towards=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
 the
negative, it=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D99s not surprising t=
hat ev=3D
entual=3D3D
ly, th=3D3D3D
e time=3D3D3D3D
 spent=3D3D3D3D3D
 writi=3D3D3D3D3D3D
ng
documentation is reallocated to other, more utility-producing activities.</=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
p>

<h1 id=3D3D3D3D3D3D3D"death-spiral">Death Spiral</h1>

<p>The combination of these two situations is self-reinforcing.  While a
suitably motivated reader <em>might</em> start by strictly looking for
documentation, or an author initially be enthused to always fully
documenting their work, over time the =3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D=
3D3D3D=3D
9Crefl=3D3D
ex=3D3D3D3D3=3D3D3D
D3DE2=3D3D3D3D3D=3D3D3D3D
3D80=3D3D3D3D3D3D9D =3D3D3D3D3D
will be for =3D3D3D3D3D3D
readers to just
go ask someone, because =3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D9Cthere=
=3D3D3D3D=3D
3D3DE2=3D3D
=3D3D3D3D3D3D80=3D3D3D
=3D3D3D3D3D3D99s ne=3D3D3D3D
ver any docu=3D3D3D3D3D
mentation!=3D3D3D3D3D3D
=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D9D, and for authors
to not write documentation because =3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3=
D3D9Cn=3D
obody =3D3D
bother=3D3D3D
s to r=3D3D3D3D
ead wh=3D3D3D3D3D
at I w=3D3D3D3D3D3D
rite
anyway!=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D9D.</p>

<p>It is important to recognise that this iterative feedback loop is the
=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D9Cnatural state=3D3D3D3D3D3DE2=
=3D3D3D3D3D3=3D
D80=3D3D3D3D3D=3D3D
3D9D of the =3D3D3D
reader/autho=3D3D3D3D
r ecosystem,=3D3D3D3D3D
 resulting i=3D3D3D3D3D3D
n something akin
to <a href=3D3D3D3D3D3D3D"https://en.wikipedia.org/wiki/Entropy">thermodyna=
mi=3D
c =3D3D
en=3D3D3D
tr=3D3D3D3D
op=3D3D3D3D3D
y<=3D3D3D3D3D3D
/a>.  To avoid
the system descending into chaos, energy needs to be constantly applied to
keep the system in order.</p>

<h1 id=3D3D3D3D3D3D3D"the-solution">The Solution</h1>

<p>Effective methods for avoiding the vicious circle can be derived from the
things that cause it.  Change the forces that apply themselves to readers
and authors, and they will behave differently.</p>

<p>On the reader=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D99s side, the mo=
st eff=3D
ective=3D3D
 way t=3D3D3D
o enco=3D3D3D3D
urage =3D3D3D3D3D
people=3D3D3D3D3D3D
 to read
documentation is for it to consistently exist.  This means that those in
control of a project or system mustn=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D=
3D3D99=3D
t cons=3D3D
ider s=3D3D3D
omethi=3D3D3D3D
ng =3D3D3D3D3D3D=3D3D3D3D3D
E2=3D3D3D3D3D3D80=3D3D3D3D3D3D9C=3D3D3D3D3D3D
done=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D9D until the
documentation is in a good state.  Patches shouldn=3D3D3D3D3D3DE2=3D3D3D3D3=
D3D8=3D
0=3D3D3D=3D3D
3D3D3D=3D3D3D
99t be=3D3D3D3D
 lande=3D3D3D3D3D
d, and=3D3D3D3D3D3D
 releases
shouldn=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D99t be made, unless the d=
ocumen=3D
tation=3D3D
 is al=3D3D3D
tered =3D3D3D3D
to mat=3D3D3D3D3D
ch the
functional changes being made.  Yes, this requires discipline, which is just
a form of energy application to prevent entropic decay.</p>

<p>Writing documentation should be an explicit and well-understood part of
somebody=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D99s job description.  Wh=
oever =3D
is res=3D3D
ponsib=3D3D3D
le for=3D3D3D3D
 docum=3D3D3D3D3D
entati=3D3D3D3D3D3D
on needs
to be given the time to do it properly.  Writing well takes time and mental
energy, and that time needs to be factored into the plans.  Never forget
that skimping on documentation, like short-changing QA or customer support,
is a false economy that will cost more in the long term than it saves in the
short term.</p>

<p>Even if the documentation exists, though, some people are going to tend
towards asking people rather than consulting the documentation.  This isn=
=3D3D
=3D3D3D3D
=3D3D3D3D3D3D
=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D99t
a moral failing on their part, but only happens when they believe that
asking someone is more beneficial to them than going to the documentation. =
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D

To change the behaviour, you need to change the belief.</p>

<p>You <em>could</em> change the belief by increasing the =3D3D3D3D3D3DE2=
=3D3D3=3D
D3D3=3D3D
D3D8=3D3D3D
0=3D3D3D3D3D=3D3D3D3D
3D9Cco=3D3D3D3D3D
st=3D3D3D3D3D3DE2=3D3D3D3D3D3D
=3D3D3D3D3D3D80=3D3D3D3D3D3D9D of asking.  You could
fire (or hellban) anyone who ever asks a question that is answered in the
documentation.  But you shouldn=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D9=
9t.  Y=3D
ou cou=3D3D
ld yell
=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D9C<a href=3D3D3D3D3D3D3D"http://=
www.catb=3D
.org/jar=3D3D
gon/html=3D3D3D
/R/RTFM.=3D3D3D3D
html">RT=3D3D3D3D3D
FM</a>!=3D3D3D3D3D3D
=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D9D at everyone who
asks a question.  Thankfully that=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3=
D99s o=3D
ne acr=3D3D
onym t=3D3D3D
hat=3D3D3D3D3D=3D3D3D3D
3DE2=3D3D3D3D3D3D8=3D3D3D3D3D
0=3D3D3D3D3D3D99s fall=3D3D3D3D3D3D
ing out of
favour.</p>

<p>Alternately, you can reduce the =3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3=
D3D9Cc=3D
ost=3D3D3D=3D3D
3D3D3DE2=3D3D3D
=3D3D3D3D3D3D80=3D3D3D3D
=3D3D3D3D3D3D9D of ge=3D3D3D3D3D
tting the an=3D3D3D3D3D3D
swer from the
documentation.  Possibly the largest single productivity boost for
programmers, for example, has been the existence of Google.  Whatever your
problem, there=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D99s a pretty good =
chance=3D
 that =3D3D
a sear=3D3D3D
ch or =3D3D3D3D
two wi=3D3D3D3D3D
ll fin=3D3D3D3D3D3D
d a
solution.  For your private documentation, you probably don=3D3D3D3D3D3DE2=
=3D3D=3D
3D3D=3D3D
3D3D=3D3D3D
80=3D3D3D3D
=3D3D3D3D3D3D99t=3D3D3D3D3D
 have =3D3D3D3D3D3D
the power
of Google available, but decent full-text search systems are available.  Use
them.</p>

<p>Finally, authors would benefit from more positive reinforcement.  If you
find good documentation, let the author know!  It requires a lot of effort
(comparatively) to look up an author=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D=
3D3D99=3D
s cont=3D3D
act de=3D3D3D
tails =3D3D3D3D
and se=3D3D3D3D3D
nd the=3D3D3D3D3D3D
m a nice
e-mail.  The =3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D9Clike=3D3D3D3D3D3D=
E2=3D3D3D3=3D
D3D3D80=3D3D3D=3D3D
3D3D3D9D but=3D3D3D
ton is a mor=3D3D3D3D
e low-energy=3D3D3D3D3D
 way of achi=3D3D3D3D3D3D
eving a similar
outcome =3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D93 you click the button,=
 and t=3D
he aut=3D3D
hor ge=3D3D3D
ts a w=3D3D3D3D
arm, f=3D3D3D3D3D
uzzy f=3D3D3D3D3D3D
eeling.=3D3D3D3D3D3D20
If your internal documentation system doesn=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=
=3D3D3D3=3D
D3D3D9=3D3D
9t hav=3D3D3D
e some=3D3D3D3D
 way t=3D3D3D3D3D
o =3D3D3D3D3D3DE2=3D3D3D3D3D3D
=3D3D3D3D3D3D80=3D3D3D3D3D3D9Cclose the
loop=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D9D and let readers easily gi=
ve aut=3D
hors a=3D3D
 bit o=3D3D3D
f kudo=3D3D3D3D
s, fix=3D3D3D3D3D
 it so=3D3D3D3D3D3D
 it does. </p>

<p>Heck, even if authors just know that a page they wrote was loaded <code>=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
N</code> times
in the past week, that=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D99s better=
 than =3D
the cu=3D3D
rrent =3D3D3D
situat=3D3D3D3D
ion, i=3D3D3D3D3D
n which
deafening silence persists, punctuated by the occasional plaintive cry of
=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D9CHey, do you know how to=3D3D3D=
3D3D3DE2=3D
=3D3D3D3D3D3=3D3D
D80=3D3D3D3D3D3D=3D3D3D
A6?=3D3D3D3D3D3DE2=3D3D3D3D
=3D3D3D3D3D3D80=3D3D3D3D3D3D9D.</p>

<p>Do you have any other ideas for how to encourage readers to read, and for
authors to write?</p>

<hr />
			<div id=3D3D3D3D3D3D3D"comments">
			=3D3D3D3D3D3D09
					<h1>4 Comments</h1>
			=3D3D3D3D3D3D09
			=3D3D3D3D3D3D09
					<div class=3D3D3D3D3D3D3D"comment odd">
						<p class=3D3D3D3D3D3D3D"comment_header">
							From:=3D3D3D3D3D3D20
								<a href=3D3D3D3D3D3D3D"http://bahumbug.wordpress.com/">niq</a>
						=3D3D3D3D3D3D09
							<br />
							<span class=3D3D3D3D3D3D3D"comment_date">2015-02-15 20:50</span>
						</p>
						<p>
							<p>There=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D99s an opposite f=
ace of=3D
 docum=3D3D
entati=3D3D3D
on.  N=3D3D3D3D
amely,=3D3D3D3D3D
 someo=3D3D3D3D3D3D
ne produces it, then the system documented changes but the documentation li=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
ves on.  Practices that were right for 1995 become magical incantations in =
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
2015, fossilised in 1000 long-forgotten (except by google) tutorials that c=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
opied a recipe that was originally an ugly hack to work around a long-since=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
-fixed defect.</p>

<p>Deeply thought through documentation - at the level of a decent book - c=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
an have a longer shelf life.  Up to a point!  One solution that helps is fo=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
r communities to value contributors to their documentation at the same leve=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
l as those who code.  Of course some do both, but if you hack you=3D3D3D3D3=
D3=3D
DE=3D3D
2=3D3D3D
=3D3D3D3D3D=3D3D3D3D
3D80=3D3D3D3D3D
=3D3D3D3D3D3D99r=3D3D3D3D3D3D
e continually up against a dilemma: when you think about something deeply e=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
nough to document it, you naturally see how to improve it.  Can you resist =
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
doing that before documenting the unimproved version?  OK, now you=3D3D3D3D=
3D=3D
3D=3D3D
E2=3D3D3D
=3D3D3D3D
=3D3D3D3D3D3D8=3D3D3D3D3D
0=3D3D3D3D3D3D99=3D3D3D3D3D3D
ve patched it you find another issue, and the docs get pushed back again!</=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
p>

<p>Low-level doxygen-style stuff is always good: it=3D3D3D3D3D3DE2=3D3D3D3D=
3D3D=3D
80=3D3D
=3D3D3D3D3D3=3D3D3D
D99s u=3D3D3D3D
seful,=3D3D3D3D3D
 and l=3D3D3D3D3D3D
ow effort to maintain.  But for higher-level stuff, both google and just-as=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
k will surely remain essential tools.</p>

<p>More of my thoughts on the subject at https://bahumbug.wordpress.com/cat=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
egory/documentation/</p>

						</p>
					</div>
			=3D3D3D3D3D3D09
					<div class=3D3D3D3D3D3D3D"comment even">
						<p class=3D3D3D3D3D3D3D"comment_header">
							From:=3D3D3D3D3D3D20
								<a href=3D3D3D3D3D3D3D"http://reddit.com/r/dredmorbius">dredmorbius=
</=3D
a>
						=3D3D3D3D3D3D09
							<br />
							<span class=3D3D3D3D3D3D3D"comment_date">2015-02-16 16:38</span>
						</p>
						<p>
							<p>A few comments:</p>

<ul>
  <li>
    <p>Responding to support requests <em>with the specific and relevant do=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
cs</em> is quite useful.  It reduces your workload, allows you to vet that =
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
the docs exist, and publicizes them.</p>
  </li>
  <li>
    <p>From the HN discussion:  having a comprehensive internal search util=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
ity which can scan multiple document formats (HTML, PDF, ePub, Word, Excel,=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
 Powerpoint, etc.) is highly useful.</p>
  </li>
  <li>
    <p><strong>Use tools that allow for eBook outputs.</strong>  Today, wit=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
h Pandoc, that=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D99s pretty much <e=
m>anyt=3D
hing</=3D3D
em>, b=3D3D3D
ut hav=3D3D3D3D
ing do=3D3D3D3D3D
cs tha=3D3D3D3D3D3D
t you can export to ePub and carry on a tablet or eBook reader are a lifesa=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
ver.  Getting the update schedule worked out may take some doing but for Op=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
s and Eng work, I=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D99d make this a=
 manda=3D
te.</p>
  </li>
</ul>

						</p>
					</div>
			=3D3D3D3D3D3D09
					<div class=3D3D3D3D3D3D3D"comment odd">
						<p class=3D3D3D3D3D3D3D"comment_header">
							From:=3D3D3D3D3D3D20
								<a href=3D3D3D3D3D3D3D"">Justin Andrusk</a>
						=3D3D3D3D3D3D09
							<br />
							<span class=3D3D3D3D3D3D3D"comment_date">2015-02-17 10:53</span>
						</p>
						<p>
							<p>For me refusing to answer questions covered in the documentation.=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
 keep sending them links til they stop bothering you.</p>

						</p>
					</div>
			=3D3D3D3D3D3D09
					<div class=3D3D3D3D3D3D3D"comment even">
						<p class=3D3D3D3D3D3D3D"comment_header">
							From:=3D3D3D3D3D3D20
								<a href=3D3D3D3D3D3D3D"">Andrew</a>
						=3D3D3D3D3D3D09
							<br />
							<span class=3D3D3D3D3D3D3D"comment_date">2015-03-10 20:41</span>
						</p>
						<p>
							<p>Like!!, Did I say that already?
Yeahh , this is really pretty much of what I like right now, so I want to g=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
ive you some Feedback, hope my comment will not be roboted by the evil forc=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
es out there, I wrote it manually, and I want humen readers, if any.
Maybe you are wrong patially, some people might not write any docs because =
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
the don=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D99t want to be docs.=3D3D=
3D3D3D3D=3D
20
It is kind of frustrating, comletely dissatisfying, when, actually you woul=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
d be a doctor already in the Windows-world, but, well you are in the Linux-=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
world, thus you sit at home at your own desk and can=3D3D3D3D3D3DE2=3D3D3D3=
D3D3=3D
D80=3D3D
=3D3D3D3D3D=3D3D3D
3D99t =3D3D3D3D
even f=3D3D3D3D3D
ind an=3D3D3D3D3D3D
y paid job, say for three years, plus.
Also you don=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D99t only want to ba =
a doc,=3D
 you a=3D3D
lso do=3D3D3D
n=3D3D3D3D3D3D=3D3D3D3D
E2=3D3D3D3D3D3D80=3D3D3D3D3D
=3D3D3D3D3D3D99t want t=3D3D3D3D3D3D
o produce content for other docs and professors to spend their time reading=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
 your documentation. If they are really interested in things and how stuff =
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
works, they can still read the source code, maybe in some cases well-commen=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
ted source-code can be more informative and instructive, than any text-only=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
-documentation might be.
So in my opinion, not everyone needs to write separate text-documentation, =
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
especially, when they are not paid for doing so.
Maybe you are the guy, that writes the tool, that extracts comments from so=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
urce-code in order to produce some generic text-only documntation for those=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
, who say, =3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D98code really makes m=
y eyes=3D
 bleed=3D3D
 (or m=3D3D3D
y fing=3D3D3D3D
er tip=3D3D3D3D3D
s), I =3D3D3D3D3D3D
absolutely can=3D3D3D3D3D3DE2=3D3D3D3D3D3D80=3D3D3D3D3D3D99t stand it=3D3D3=
D3D3D3DE=3D
2=3D3D3D3D3D=3D3D
3D80=3D3D3D3D3D3=3D3D3D
D99.</p>

						</p>
					</div>
			=3D3D3D3D3D3D09
				<h1>Post a comment</h1>
				<p style=3D3D3D3D3D3D3D"font-style: italic">
					All comments are held for moderation; markdown formatting accepted.
				</p>
				<form id=3D3D3D3D3D3D3D"anothercommentform" method=3D3D3D3D3D3D3D"POST"=
 act=3D
ion=3D3D
=3D3D3D3D3D=3D3D3D
3D3D"h=3D3D3D3D
ttp://=3D3D3D3D3D
www.he=3D3D3D3D3D3D
zmatt.org/~mpalmer/blog/comment.php">
					<input type=3D3D3D3D3D3D3D"hidden" name=3D3D3D3D3D3D3D"post_id" value=
=3D3D3D=3D
3D3D3D=3D3D
3D"/bl=3D3D3D
og/201=3D3D3D3D
5/02/1=3D3D3D3D3D
5/the-=3D3D3D3D3D3D
documentation-vicious-circle" />
					<table style=3D3D3D3D3D3D3D"display: none">
						<tr>
							<th colspan=3D3D3D3D3D3D3D"2">
								This is a honeypot form.  Do not use this form unless you want to g=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
et
								your IP address blacklisted.  Use the second form below for comment=
=3D
=3D3D
=3D3D3D
=3D3D3D3D
=3D3D3D3D3D
=3D3D3D3D3D3D
s.
							</th>
						<tr>
							<th>Name:</th>
							<td><input type=3D3D3D3D3D3D3D"text" size=3D3D3D3D3D3D3D"25" name=3D=
3D3D3D=3D
3D3D3D=3D3D
"name"=3D3D3D
 /> (r=3D3D3D3D
equire=3D3D3D3D3D
d)</td>
						</tr>
						<tr>
							<th>E-mail:</th>
							<td><input type=3D3D3D3D3D3D3D"text" size=3D3D3D3D3D3D3D"25" name=3D=
3D3D3D=3D
3D3D3D=3D3D
"email=3D3D3D
" /> (=3D3D3D3D
requir=3D3D3D3D3D
ed, no=3D3D3D3D3D3D
t published)</td>
						</tr>
						<tr>
							<th>Website:</th>
							<td><input type=3D3D3D3D3D3D3D"text" size=3D3D3D3D3D3D3D"25" name=3D=
3D3D3D=3D
3D3D3D=3D3D
"link"=3D3D3D
 /> (o=3D3D3D3D
ptiona=3D3D3D3D3D
l)</td>
						</tr>
						<tr>
							<td colspan=3D3D3D3D3D3D3D"2"><textarea name=3D3D3D3D3D3D3D"comment"=
 row=3D
s=3D3D3D=3D3D
3D3D3D=3D3D3D
3D"10"=3D3D3D3D
 cols=3D3D3D3D3D
=3D3D3D3D3D3D3D"60"=3D3D3D3D3D3D
 ></textarea></td>
						</tr>
						<tr>
							<td><input type=3D3D3D3D3D3D3D"submit" name=3D3D3D3D3D3D3D"submit" v=
alue=3D
=3D3D3D3=3D3D
D3D3D3=3D3D3D
D"Subm=3D3D3D3D
it Com=3D3D3D3D3D
ment" =3D3D3D3D3D3D
/></td>
						</tr>
					</table>
				</form>
				<form id=3D3D3D3D3D3D3D"commentform" method=3D3D3D3D3D3D3D"POST" action=
=3D3D3=3D
D3D3D3=3D3D
D3D"ht=3D3D3D
tp://w=3D3D3D3D
ww.hez=3D3D3D3D3D
matt.o=3D3D3D3D3D3D
rg/~mpalmer/blog/commentsubmit.php">
					<input type=3D3D3D3D3D3D3D"hidden" name=3D3D3D3D3D3D3D"post_id" value=
=3D3D3D=3D
3D3D3D=3D3D
3D"/bl=3D3D3D
og/201=3D3D3D3D
5/02/1=3D3D3D3D3D
5/the-=3D3D3D3D3D3D
documentation-vicious-circle" />
					<table>
						<tr>
							<th>Name:</th>
							<td><input type=3D3D3D3D3D3D3D"text" size=3D3D3D3D3D3D3D"25" name=3D=
3D3D3D=3D
3D3D3D=3D3D
"name"=3D3D3D
 /> (r=3D3D3D3D
equire=3D3D3D3D3D
d)</td>
						</tr>
						<tr>
							<th>E-mail:</th>
							<td><input type=3D3D3D3D3D3D3D"text" size=3D3D3D3D3D3D3D"25" name=3D=
3D3D3D=3D
3D3D3D=3D3D
"email=3D3D3D
" /> (=3D3D3D3D
requir=3D3D3D3D3D
ed, no=3D3D3D3D3D3D
t published)</td>
						</tr>
						<tr>
							<th>Website:</th>
							<td><input type=3D3D3D3D3D3D3D"text" size=3D3D3D3D3D3D3D"25" name=3D=
3D3D3D=3D
3D3D3D=3D3D
"link"=3D3D3D
 /> (o=3D3D3D3D
ptiona=3D3D3D3D3D
l)</td>
						</tr>
						<tr>
							<td colspan=3D3D3D3D3D3D3D"2"><textarea name=3D3D3D3D3D3D3D"comment"=
 row=3D
s=3D3D3D=3D3D
3D3D3D=3D3D3D
3D"10"=3D3D3D3D
 cols=3D3D3D3D3D
=3D3D3D3D3D3D3D"60"=3D3D3D3D3D3D
 ></textarea></td>
						</tr>
						<tr>
							<td><input type=3D3D3D3D3D3D3D"submit" name=3D3D3D3D3D3D3D"submit" v=
alue=3D
=3D3D3D3=3D3D
D3D3D3=3D3D3D
D"Subm=3D3D3D3D
it Com=3D3D3D3D3D
ment" =3D3D3D3D3D3D
/></td>
						</tr>
					</table>
				</form>
			</div>
			<div id=3D3D3D3D3D3D3D"page-navigation">=3D3D3D3D3D3D20
				<div class=3D3D3D3D3D3D3D"clear"><a href=3D3D3D3D3D3D3D"/~mpalmer/kitte=
ns.p=3D
hp">=3D3D
<!--=3D3D3D
 Who=3D3D3D3D
 doe=3D3D3D3D3D
sn't=3D3D3D3D3D3D
 love kittens? --></a>&nbsp;</div>
				<div class=3D3D3D3D3D3D3D"left">=3D3D3D3D3D3D20
				=3D3D3D3D3D3D20
					<a href=3D3D3D3D3D3D3D"http://www.hezmatt.org/~mpalmer/blog/2014/11/23=
/y=3D
ou=3D3D
-s=3D3D3D
ta=3D3D3D3D
y-=3D3D3D3D3D
cl=3D3D3D3D3D3D
assy-uber.html" title=3D3D3D3D3D3D3D"Previous Post: You stay classy, Uber">=
&l=3D
aq=3D3D
uo=3D3D3D
; =3D3D3D3D
Yo=3D3D3D3D3D
u =3D3D3D3D3D3D
stay classy, Uber</a>
				=3D3D3D3D3D3D20
				</div>=3D3D3D3D3D3D20
				<div class=3D3D3D3D3D3D3D"right">=3D3D3D3D3D3D20
				=3D3D3D3D3D3D20
				</div>=3D3D3D3D3D3D20
				<div class=3D3D3D3D3D3D3D"clear">&nbsp;</div>=3D3D3D3D3D3D20
			</div>

			</div>
		</div>
		<div id=3D3D3D3D3D3D3D"footer">
			<a href=3D3D3D3D3D3D3D"http://anybrowser.org/">
				<img src=3D3D3D3D3D3D3D"http://www.hezmatt.org/~mpalmer/brain.png"
					alt=3D3D3D3D3D3D3D"Best Viewed with a brain" />
			</a>
			<a href=3D3D3D3D3D3D3D"http://github.com/mojombo/jekyll">
				Powered by Jekyll!
			</a>
			<a href=3D3D3D3D3D3D3D"http://validator.w3.org/check/referer">
				<img src=3D3D3D3D3D3D3D"http://www.hezmatt.org/~mpalmer/valid-html40.pn=
g"
					alt=3D3D3D3D3D3D3D"Valid HTML 4.0!" height=3D3D3D3D3D3D3D"31" width=3D=
3D3D3D=3D
3D3D3D=3D3D
"88" />
			</a>

		</div>

	</body>
</html>