<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<p><br>
</p>
<div class="moz-cite-prefix">On 17/10/19 11:44 am, Nathan Woodrow
wrote:<br>
</div>
<blockquote type="cite"
cite="mid:CAAi8Yg9U-kmKL4BP9bFFmcrM618q8A75MuO1Q-Y1=LDDr8qVmQ@mail.gmail.com">
<div>I think we have to be very careful taking the results of a
limited survey and making major changes to the project. It's a
sample set but only a very very small sample set. </div>
<div> </div>
<div>There has been a bit of talk around the documentation but
reducing the efforting is the wrong way to go and I don't think
we should support that move as it will just lead to no
documentation which is how we started. This is a problem for
even large enterprise companies so we will not find a quick fix
or one that works right 100% of the time. <br>
</div>
</blockquote>
<p>I have quite a few thoughts to add to this thread, but probably
won't have the bandwidth to give it due attention for a few weeks.</p>
<p>But I think it is worth extending Nathan's comment here by
referencing a highly regarded article in Tech Writing circles from
Daniele Procida titled: What nobody tells you about
documentation. <a
href="https://www.divio.com/blog/documentation/">https://www.divio.com/blog/documentation/<br>
</a></p>
<p>Key message:</p>
<p><i style="color: rgb(34, 34, 34); font-family: Arial, Tahoma,
Helvetica, FreeSans, sans-serif; font-size: 13.2px;
font-variant-ligatures: normal; font-variant-caps: normal;
font-weight: 400; letter-spacing: normal; orphans: 2;
text-align: start; text-indent: 0px; text-transform: none;
white-space: normal; widows: 2; word-spacing: 0px;
-webkit-text-stroke-width: 0px; background-color: rgb(255, 255,
255); text-decoration-style: initial; text-decoration-color:
initial;">There is a secret that needs to be understood in order
to write good software documentation: there isn’t one thing
called documentation, there are four. They are: </i><br
style="color: rgb(34, 34, 34); font-family: Arial, Tahoma,
Helvetica, FreeSans, sans-serif; font-size: 13.2px; font-style:
normal; font-variant-ligatures: normal; font-variant-caps:
normal; font-weight: 400; letter-spacing: normal; orphans: 2;
text-align: start; text-indent: 0px; text-transform: none;
white-space: normal; widows: 2; word-spacing: 0px;
-webkit-text-stroke-width: 0px; background-color: rgb(255, 255,
255); text-decoration-style: initial; text-decoration-color:
initial;">
</p>
<ul style="padding: 0px 2.5em; margin: 0.5em 0px; line-height: 1.4;
color: rgb(34, 34, 34); font-family: Arial, Tahoma, Helvetica,
FreeSans, sans-serif; font-size: 13.2px; font-style: normal;
font-variant-ligatures: normal; font-variant-caps: normal;
font-weight: 400; letter-spacing: normal; orphans: 2; text-align:
start; text-indent: 0px; text-transform: none; white-space:
normal; widows: 2; word-spacing: 0px; -webkit-text-stroke-width:
0px; background-color: rgb(255, 255, 255); text-decoration-style:
initial; text-decoration-color: initial;">
<li style="padding: 0px; margin: 0px 0px 0.25em; text-indent:
0px;"><i>Tutorials, </i></li>
<li style="padding: 0px; margin: 0px 0px 0.25em; text-indent:
0px;"><i>How-to guides, </i></li>
<li style="padding: 0px; margin: 0px 0px 0.25em; text-indent:
0px;"><i>Explanations and </i></li>
<li style="padding: 0px; margin: 0px 0px 0.25em; text-indent:
0px;"><i>Technical references. </i></li>
</ul>
<i style="color: rgb(34, 34, 34); font-family: Arial, Tahoma,
Helvetica, FreeSans, sans-serif; font-size: 13.2px;
font-variant-ligatures: normal; font-variant-caps: normal;
font-weight: 400; letter-spacing: normal; orphans: 2; text-align:
start; text-indent: 0px; text-transform: none; white-space:
normal; widows: 2; word-spacing: 0px; -webkit-text-stroke-width:
0px; background-color: rgb(255, 255, 255); text-decoration-style:
initial; text-decoration-color: initial;">They represent four
different purposes or functions, and require four different
approaches to their creation. Understanding the implications of
this will help improve most software documentation - often
immensely.</i>
<p>I'd suggest that the metrics we see about people using
StackExchange answers is that they are solving goal oriented
problems (which fits into the How-to guides section). It is good
and we should encourage its continued use. However all the other
documentation types are very important to users at different times
in their development journey. <br>
</p>
<i style="color: rgb(34, 34, 34); font-family: Arial, Tahoma,
Helvetica, FreeSans, sans-serif; font-size: 13.2px;
font-variant-ligatures: normal; font-variant-caps: normal;
font-weight: 400; letter-spacing: normal; orphans: 2; text-align:
start; text-indent: 0px; text-transform: none; white-space:
normal; widows: 2; word-spacing: 0px; -webkit-text-stroke-width:
0px; background-color: rgb(255, 255, 255); text-decoration-style:
initial; text-decoration-color: initial;"></i>
<pre class="moz-signature" cols="72">--
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant
M +61 (0) 419 142 254</pre>
</body>
</html>