<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<p>I've written a detailed analysis about the significant challenges
faced by the QGIS documentation team. (QGIS is an open source
desktop geospatial application).</p>
<p>While research is specific to QGIS, I feel the lessons are
broadly applicable to most successful open source projects. I'd be
interested to hear feedback, and in particular, would be
interested to hear whether the lessons should help frame next
year's Google Season of Docs.</p>
<p>Tweet: <a
href="https://twitter.com/cameronshorter/status/1203528611740831744">https://twitter.com/cameronshorter/status/1203528611740831744</a></p>
<p>Blog post: <a
href="https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html">https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html</a></p>
<h2 style="margin: 0px; position: relative; font-size: 22px; color:
rgb(34, 34, 34); font-family: Arial, Tahoma, Helvetica, FreeSans,
sans-serif; font-style: normal; font-variant-ligatures: normal;
font-variant-caps: normal; 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;">Summary</h2>
<span 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; display: inline
!important; float: none;">Many have tried to help QGIS docs, with
limited success. I’ve collated insightful quotes from a bunch of
their stories and then postulate solutions. Surprisingly, the
biggest problem isn’t a lack of tech writers or complicated tools
(although they are factors).</span><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;">
<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;">
<span 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; display: inline
!important; float: none;">Problems centre around:</span><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;">
<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;">Poorly capturing community good-will and offers of
assistance;</li>
<li style="padding: 0px; margin: 0px 0px 0.25em; text-indent:
0px;">A lack of direction;</li>
<li style="padding: 0px; margin: 0px 0px 0.25em; text-indent:
0px;">Struggling to keep up with a rapidly evolving software
baseline;</li>
<li style="padding: 0px; margin: 0px 0px 0.25em; text-indent:
0px;">Insufficient writing expertise;</li>
<li style="padding: 0px; margin: 0px 0px 0.25em; text-indent:
0px;">A high technical barrier to entry;</li>
<li style="padding: 0px; margin: 0px 0px 0.25em; text-indent:
0px;">Documentation and training being generated outside of the
core project;</li>
<li style="padding: 0px; margin: 0px 0px 0.25em; text-indent:
0px;">Awkward documentation tools and processes.</li>
</ul>
<span 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; display: inline
!important; float: none;">This leads to an immediate case to:</span><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;">
<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;">Define and evangelise a vision and roadmap.</li>
<li style="padding: 0px; margin: 0px 0px 0.25em; text-indent:
0px;">Prioritise funding and lobby sponsors to resource the
vision.</li>
<li style="padding: 0px; margin: 0px 0px 0.25em; text-indent:
0px;">Implement an information architecture review.</li>
<li style="padding: 0px; margin: 0px 0px 0.25em; text-indent:
0px;">Sustain a community evangelist/coordinator to attract and
nurture a broader doc community.</li>
<li style="padding: 0px; margin: 0px 0px 0.25em; text-indent:
0px;">Sustain a trained technical writer to amplify the quality
and effectiveness of the community.</li>
<li style="padding: 0px; margin: 0px 0px 0.25em; text-indent:
0px;">Attract external docs back into the core.</li>
</ul>
<span 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; display: inline
!important; float: none;">Medium-term:</span><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;">
<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;">Ask the greater open-source community to address the
usability of documentation tools and reduce the technical
barrier to entry. Adopt improvements as they are developed.</li>
<li style="padding: 0px; margin: 0px 0px 0.25em; text-indent:
0px;">Align with best the practices evolving within<span> </span><a
href="https://thegooddocsproject.dev/" style="text-decoration:
none; color: rgb(136, 136, 136);">TheGoodDocsProject</a>.</li>
</ul>
<p><span 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; display: inline !important; float: none;">While
acknowledging the great work done to date, I feel the QGIS docs
team has insufficient capacity and availability to skills to
drive this agenda. Targeted and sustained investment should be
applied to bring the quality of QGIS docs up to the quality of
the software.</span></p>
<p><span 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; display: inline !important; float: none;">More: ... </span><span
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; display: inline !important; float: none;"><a
href="https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html">https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html</a></span></p>
<pre class="moz-signature" cols="72">--
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant
M +61 (0) 419 142 254</pre>
</body>
</html>