Home »

Write the Docs Newsletter – October 2018

Hi folks!

Kelly O. here, wishing you a happy October! I hope the change of season, whether it’s fall or spring, is starting out well for everybody! Although nearly a month has passed, the good vibes from the Prague conference are still lingering (at least for me!). We were really proud and excited to see such a crowd turn out for our fifth European conference. As usual, we had an awesome batch of speakers, a bustling writing day, a vibrant unconf track, and just generally a great few days of getting to interact with the community in real life. If you missed out on the conference, you can catch up on the talk videos on our YouTube channel.

Also, while every single one of our lightning talks this year was stellar (they’re included in the playlist above), I would be remiss if I didn’t call out what was one of the best moments of any Write the Docs conference I’ve been to. On Tuesday afternoon, a particularly intrepid group of attendees got up on stage and delivered a lightning talk in the form of a documentation-themed, a capella cover of Michael Jackson’s ‘Man in the Mirror’. I cried from laughing (and also, if I’m honest, from community feels). Don’t miss it.

If you’re dying to get in on a Write the Docs conference before the end of the year, you have one more chance! Our Australian conference is coming up November 15-16 in Melbourne, and we would love to have you join us! Check out the conference website to peruse the great line up of speakers and to buy your ticket!

Before we jump into stories, I just wanted to say – as this my last issue – thank you all so much for letting me take up space in your inboxes over the last couple of years! It’s been a real pleasure. We have an excellent editor lined up to take the reins, but I’ll let her introduce herself next issue. Rest assured, you’re in great hands. ;)

Now, let’s see what folks have been talking about this month!

To prompt, or not to prompt, that is the question

We had a great conversation emerge this month that is at once very narrow in scope – the whole thing revolves around just 1 or 2 characters – and broadly relevant to anyone writing docs that include code samples. The question at its heart: What’s the best way to handle command prompts in code samples?

There’s a surprising number of considerations to account for here. First, depending on your reader’s environment, the prompt they’re used to staring at might vary. Second, is it safe to assume that everyone will interpret a $ or a # at the beginning of a line as a prompt and not as part of the command? (Probably not, was the feeling.) Third, if you’re including code samples in your docs, you should also be optimizing them for copying and pasting. Including the prompt, while it does provide some context, means your reader has to manually remove it if they’re copying and pasting into the command line.

The general consensus was to strike a balance by including the prompt character in the code samples, but preventing it from being copied and pasted with a little bit of CSS wizardry. You can see examples of how this looks in Stripe’s documentation. And this blog post covers a handful of approaches to making text unselectable.

If you’re ever struggling with code sample styling in your own docs, pop into #documenting-apis

Resources for planning out your information architecture

Often, when tackling a new docs project, one of the biggest challenges can be figuring out how to approach your information architecture. This month, a user came to the WTD hivemind for help with this very problem. Many of the good documentarians of Slack jumped in to share an excellent array of IA and user testing resources:

If you can’t get enough IA, check out the #infoarchitecture channel on Slack.

Task management tools for docs teams

While we often discuss the tools we use to create our documentation, we also, from time to time, compare our other tool sets. This month, there was a hearty discussion on to topic of task management tools. In the age of “Docs Like Code,” many documentarians have also begun to adopt doing “Tasks Like Code”. In other words, many docs teams use similar task management tools as developers, such as Jira or GitHub issues. This approach comes with its own benefits and challenges.

Benefits:

  • Easier alignment with development & QA teams
  • Built-in sprint planning tools

Challenges:

  • Viewing all documentation-related tasks at once
  • Developer tasks and documentation tasks not being one-to-one

Of course, there are those of us who use non-developer driven task management tools – either instead of or in addition to those tools – such as Trello, Asana, or Flow.

While we may use different tools, what matters in the end is that you utilize a task management tool (or tool set) that works for you!

Have more thoughts about your toolset? Come share them in #doctools or one of the many tool-specific channels we have on Slack.

Show us your workflows!

Speaking of docs-as-code, and task management for that matter, there was another great discussion this month about how to map docs-as-code to software development workflows, with special reference to agile.

Most of the conversation revolved around how to map pull requests in Github to issue tracking in tools such as Jira. Several folks who track issues with Jira start with basic issue scoring based on estimated effort (or t-shirt sizing as some people call it), and then assign tickets on a per-sprint cycle. A couple of teams mentioned using a Fibonacci sequence to determine story points for relative effort (for more information, see Atlassian’s article on story points and agile estimation).

When a PR is started, Jira tickets then move through specified phases (in one case, “In Progress”, “Tech Review”, “Editorial Review”, “Revision”, “Ready to Release”, “Published”) that map to the phases of PR review.

Some teams work on the same schedule as dev and test – that is, docs are completed during the same sprint. Other teams work on their own sprint schedules, add a week or two, or add an entire sprint cycle, to accommodate documentation lag. Sprint duration seems to range from 1-3 weeks.

Another common practice is for writers to be included in sprint planning meetings, so that the documentation and development of features are agreed on up front.

TL;DR: The closer the docs team gets to dev/code, the easier it seems to be to get a docs-as-code workflow to fall into place.

Looking for more perspectives on how best to manage docs-as-code? We’ve got just the channel for you: #docs-as-code

Upcoming community events

October 09 – Ottawa, Alberta, Canada – Structured Writing with Mark Baker

October 14 – Moscow, Russia – Second Meetup

October 15 – Amsterdam, Netherlands – To CMS or Not To CMS

October 15 – Salt Lake City, Utah, USA – Accessibility Best Practices

October 16 – Denver, Colorado, USA – Hacktoberfest! Contribute to open source docs with pizza, beer, and prizes.

October 16 – Portland, Oregon, USA – Joint Meetup with PSU & Support Driven: A Day in the Life

October 17 – Bradford, West Yorkshire, UK – Hacktoberfest! Join us in a basement in Bradford!

October 24 – Austin, Texas, USA – Engineering/Developer-focused Content: Stories and Tools for Practitioners

October 25 – Remote (Australia time) – Remote: Teaching engineers about content strategy

November 6 – Ottawa, Alberta, Canada – Monthly Ottawa Shopify Meetup

November 15 – Melbourne, Australia – Write the Docs Australia

Welcome to Portland 2019   Write the Docs Newsletter – November 2018