Blog - Posts tagged surveyhttps://www.writethedocs.org/blog/archive/tag/survey/atom.xml2017-04-03T00:00:00ZABlogWrite the Docs Newsletter - April 2017https://www.writethedocs.org/blog/newsletter-april-2017/2017-04-03T00:00:00Z2017-04-03T00:00:00ZWrite the Docs Team<div class="section" id="write-the-docs-newsletter-april-2017">
<div class="section" id="spring-has-sprung">
<h2>Spring has Sprung!</h2>
<p>In the Northern Hemisphere, anyway. In the Southern Hemisphere, Fall has…fallen? Sounds good, let’s go with it!</p>
<p>In both hemispheres, <a class="reference external" href="https://www.writethedocs.org/conf/na/2017/">Write the Docs Portland</a> approaches! We’ve announced the <a class="reference external" href="https://www.writethedocs.org/conf/na/2017/news/announcing-presentations/">presentations and speakers</a>, and you can <a class="reference external" href="https://ti.to/writethedocs/write-the-docs-na-2017/">get your ticket here</a>. We don’t expect to sell out for another couple of weeks, but if you haven’t made plans for May 14-16 yet, the perfect time is <strong>soon</strong>.</p>
</div>
<hr class="docutils" />
<div class="section" id="the-art-of-the-bug-report">
<h2>The Art of the Bug Report</h2>
<p>First up this month, someone asked the channel for a good example of how to document a bug. The community came through with suggestions for a template that includes:</p>
<ul class="simple">
<li>Environment: affected software and versions</li>
<li>Summary in narrative form, such as “While testing feature <em>x</em>, I encountered <em>z</em>.”</li>
<li>Steps to reproduce the bug</li>
<li>Results and impacts, including severity level</li>
<li>Workarounds</li>
<li>Relevant diagnostics</li>
</ul>
<p>But how to get that info into release notes? One participant reported his team’s process:</p>
<ol class="arabic simple">
<li>Collect all JIRA issues (especially customer-reported issues)</li>
<li>Filter out internal code issues and QA tests</li>
<li>Rewrite the issue title so it’s easy for readers to scan</li>
<li>Label issues so they’re easy to sort</li>
<li>Use <a class="reference external" href="https://libraries.io/github/markcraig/release-notes-list-builder">this script</a> to transpose the issues (in JSON format) from JIRA into a DocBook block element for release notes</li>
</ol>
</div>
<hr class="docutils" />
<div class="section" id="documentation-metrics-what-to-track-and-how">
<h2>Documentation Metrics: What to Track and How</h2>
<p>An interesting topic was swatted around the #watercooler this month: documentation metrics. Capturing the right information can definitely help us make targeted doc improvements, but the identifying that information – and capturing it – can be a bear. Some of the suggestions that came up included:</p>
<ul class="simple">
<li>Using referral links to track which docs people engage with the most and the least</li>
<li>Tagging support requests to find the most relevant docs</li>
<li>Using an analytics platform to identify which search terms are used most (or searched for but not found) and which results are most-clicked</li>
<li>Adding :thumbsup: and :thumbsdown: rating options to collect helpfulness ratings from users</li>
</ul>
<p>For a take on how one support team tracked the relationship between support and content, check out <a class="reference external" href="https://www.campaignmonitor.com/blog/company/2013/09/yoda-our-support-ally/">this blog post from Campaign Monitor</a>.</p>
</div>
<hr class="docutils" />
<div class="section" id="starter-kit-for-command-line-git">
<h2>Starter Kit for Command Line Git</h2>
<p>Toward the end of the month, a request for an expert to help with learning command line Git resulted in an avalanche of resources. Here’s what folks suggested for learning Git:</p>
<ul class="simple">
<li><a class="reference external" href="https://www.writethedocs.org/conf/na/2017/speakers#speaker-matthew-desmond">Git workshop at Write the Docs in May</a></li>
<li><a class="reference external" href="https://try.github.io">tryGit</a></li>
<li><a class="reference external" href="https://tsl.io/git-fire-drill/">The SilverLogic Git Fire Drill</a></li>
<li><a class="reference external" href="https://www.git-scm.com/book/en/v2">Pro Git by by Scott Chacon and Ben Straub</a></li>
<li><a class="reference external" href="http://learngitbranching.js.org">Learn Git Branching</a></li>
</ul>
<p>Also noted: there’s nothing wrong with using Git in a desktop app or on the web! Folks mentioned <a class="reference external" href="https://www.sourcetreeapp.com/">SourceTree</a> and <a class="reference external" href="https://bitbucket.org/">Bitbucket</a> as GitHub alternatives.</p>
<p>The advice for those who want to feel more at home using command line Git? Practice, practice, practice–repetition makes perfect.</p>
</div>
<hr class="docutils" />
<div class="section" id="stack-overflow-developer-survey">
<h2>2017 Stack Overflow Developer Survey</h2>
<p>The annual Stack Overflow Developer survey was released this month! <a class="reference external" href="https://stackoverflow.com/insights/survey/2017/">https://stackoverflow.com/insights/survey/2017/</a>. Among 2017’s tidbits – which include findings on the most dreaded coding language and the feasibility of sharing an office with a noisy-keyboard-user – <strong>more than 80% of respondents said that they use official documentation to learn</strong>. That was even higher than the number who used Stack Overflow, who did the survey!</p>
</div>
<hr class="docutils" />
<div class="section" id="looking-ahead">
<h2>Looking Ahead</h2>
<p>Write the Docs Portland is right on the horizon, and Write the Docs Prague isn’t going to be far behind! We’ll be opening the CFP up shortly, so now is a great time to be thinking about a talk you might want to submit! In the meantime, if May (or September) are just too far away to bear, remember you can always check out <a class="reference external" href="https://www.writethedocs.org/meetups/">your nearest meetup</a>, or <a class="reference external" href="https://www.writethedocs.org/organizer-guide/meetups/starting/">start one yourself</a>!</p>
</div>
</div>