Write the Docs Newsletter - April 2017

2017-04-03T00:00:00+00:00

Spring has Sprung!

In the Northern Hemisphere, anyway. In the Southern Hemisphere, Fall has…fallen? Sounds good, let’s go with it!

In both hemispheres, Write the Docs Portland approaches! We’ve announced the presentations and speakers, and you can get your ticket here. 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 soon.

The Art of the Bug Report

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:

Environment: affected software and versions
Summary in narrative form, such as “While testing feature x, I encountered z.”
Steps to reproduce the bug
Results and impacts, including severity level
Workarounds
Relevant diagnostics

But how to get that info into release notes? One participant reported his team’s process:

Collect all JIRA issues (especially customer-reported issues)
Filter out internal code issues and QA tests
Rewrite the issue title so it’s easy for readers to scan
Label issues so they’re easy to sort
Use this script to transpose the issues (in JSON format) from JIRA into a DocBook block element for release notes

Documentation Metrics: What to Track and How

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:

Using referral links to track which docs people engage with the most and the least
Tagging support requests to find the most relevant docs
Using an analytics platform to identify which search terms are used most (or searched for but not found) and which results are most-clicked
Adding :thumbsup: and :thumbsdown: rating options to collect helpfulness ratings from users

For a take on how one support team tracked the relationship between support and content, check out this blog post from Campaign Monitor.

Starter Kit for Command Line Git

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:

Also noted: there’s nothing wrong with using Git in a desktop app or on the web! Folks mentioned SourceTree and Bitbucket as GitHub alternatives.

The advice for those who want to feel more at home using command line Git? Practice, practice, practice–repetition makes perfect.

2017 Stack Overflow Developer Survey

The annual Stack Overflow Developer survey was released this month! https://stackoverflow.com/insights/survey/2017/. 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 – more than 80% of respondents said that they use official documentation to learn. That was even higher than the number who used Stack Overflow, who did the survey!

Looking Ahead

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 your nearest meetup, or start one yourself!