Home »

Write the Docs Newsletter - February 2017

Welcome back / Are we there yet?

Hi everybody! We’re so happy to find ourselves back in your inbox with this, the first newsletter of 2017! Although we all took some kind of break over the holiday season, we did our best to keep an eye on Slack for good newsletter nuggets – and we definitely were not disappointed! Below are some highlights from the last couple of months, and we’ll be getting back into the regular swing of things going forward. :)

The other thing that’s looming large in docsland is the North America conference, coming up in just over three months! The details are all starting to fall into place, and now’s a great time to get your tickets or submit a talk. While you’ve still got some time for ticket-buying (we don’t expect to sell out until mid-March), you definitely don’t want to dawdle on that second one – deadline for proposals is this Friday at midnight PST.

So now, without further ado, let’s look in on what the community has been discussing, over the new year.

Best practices for changing your docs workflow

A question arose, back in December, that many of us have been faced with (or perhaps daydreamed about) at some point in our careers: If you had the chance to implement a brand new documentation workflow, how would you go about it?

It’s often easy to go down the rabbit hole with a question like this, comparing the virtues of specific toolchains and markup languages. But in this case, a lot of the conversation instead revolved around some deeper, more fundamental points. Namely, how to make sure that a) the new system will be an improvement over the old system and b) that you’re making the change for the right reasons.

The general consensus was that decisions like these are fraught. It’s easy to fall into the trap of thinking that the workflow that suits you and your needs best is the best workflow for your entire team. Also, be on guard against the thought that once you switch to a new system, everything will be perfect. (This is especially true for shiny new tools that you’ve just met – the honeymoon period is real.)

So what’s the best way to approach a big process change? Per usual, there was lots of excellent advice to be had. First and foremost, make sure you know a) what problems the new system is going to solve and b) what problems it’s going to introduce (remember – no system is perfect). When you know those things, talk to the people who will be using the new system every day. Ask them what they like about their current process. Ask them where they feel pain. Then get them involved in - and ideally, give them ownership over – the transition. Anything you can do to avoid surprises will make for a much more successful roll out, in the long run.

Getting started with API Docs

“How do I get started with API documentation?” is a question we’ve overheard on Slack and IRL, on an increasingly regular basis. When it resurfaced a few weeks ago, in our #documenting-apis channel, we thought we’d take the opportunity to pull together a little collection of resources to help folks get started on their API docs journey:

If API docs are already your jam, head over to the API channel – we’d love to hear about your favorite resources!

Pros and cons of using tabbed content for multiple audiences

Writing for multiple audiences is definitely a common predicament we find ourselves in, and one writer came to the general channel with a question about using navigation tabs (navtabs) to organize their content. It sparked a lively discussion, which we’ve distilled into a quick round-up of the pros and cons of the navtab experience:

Pros

  • Allows content reuse.
  • Lets users “choose their own adventure” to get content that’s specific to their skill level, role, or need.
  • Helps users find the right information more quickly – for example, platform-, language-, or device-specific information.

Cons

  • Users who choose the wrong tab for their needs will see unhelpful or confusing information.
  • Can induce fear of missing out because users are aware that they’re only seeing one information pathway.
  • Defeats browser ‘search on this page’ functions because navtabs “hide” search terms if they appear inside a tabbed section.
  • Prevents users from scanning an entire page of information.

The general consensus was that navtabs might not be a go-to approach, but they may be the right option when other methods of organization aren’t working. Some folks suggested Stripe and Django as examples of elegant approaches for multi-audience docs. And this Tabs Used Right article was put forth as a good resource for more navtab tips.

Running an effective audit of your UI text

A request for guidance in performing a UI audit turned into an illuminating discussion the different ways you can approach the task.

Some folks mentioned working in source code – using properties files that gather up UI strings and make it easy to detect obvious infelicities or worse. Everyone agreed, though, that this approach wasn’t sufficient in an ideal world, because you need to consider text in the context of the entire UI. Not just static text but surrounding presentation and workflow are also important considerations in reviewing copy.

It was also pointed out that reviewing the UI for copy can raise larger issues of flow, information architecture, and user experience. If a project is large, some folks found that they needed to break down the UI review into stages. One of our resident UI experts suggested not only starting with the main user flows, but also to trigger as many errors or potential problems as possible.

Folks generally agreed that if a UI style guide wasn’t already in place, an audit provides a good opportunity to start developing one. Keep it iterative. Don’t reinvent the wheel (rely on existing guides where possible in developing your own, as with any other style guide). And make sure to include specific examples from your own UI!

Exploring your technical writing career options

We’re so lucky to have such rich conversations in our community – and that’s thanks, in large part, to how diverse our professional backgrounds are. One person’s question about how to expand their responsibilities beyond the bounds of a technical writer’s “traditional” job description produced a ton of useful insight.

There were a good number of folks who suggested that product management is a career path commonly trodden by technical writers. Others recommended looking at training or community management as roles that with significant overlap. Marketing, developer evangelism, and doc management also came up as possibilities to explore. As far as how to start moving in any of these directions, a strong first step would be to attend or start a meetup (or otherwise get involved in the community) for the type of work you’re interested in.

UI and UX also came up as good possibilities if you have a tech writing background – but that making that jump can sometime be particularly difficult to navigate. The general sentiment was that writers, who often serve as a primary advocate for software users, can contribute substantially to UX design and UI development. But some writers expressed their frustration with feeling excluded from the design process. One helpful suggestion for how to bridge that gap more smoothly was to start small, focusing on text-related questions or contributions, and then work gradually to gain trust and a more full-fledged role in the design process.

Looking ahead to Write the Docs North America

One last reminder that we’re in the home stretch of the call for proposals – if you’ve been thinking about pitching a talk for May’s conference, make sure you get it in before midnight (PST) on Friday. You can read all about what we’re looking for, and submit your proposal, on the CFP page. We can’t wait to see what you come up with!

Write the Docs 2016 Year in Review   New and Improved Community Code of Conduct