Adobe Robohelp

Get new posts delivered straight to your inbox.

Subscriber count: 3,881

Stitcher radio

follow us in feedly

Want more tech comm blogs to follow? See my Tech Comm Collection of Blogs on Feedly.

Adobe FrameMaker

Upcoming 2017 Write the Docs Conference in Portland

Mar 3, 2017 • findability, general

This year I'm planning to attend the 2017 Write the Docs conference in Portland. The conference takes place May 14-16 and draws about 400 people who come together for three days 'to explore the art and science of documentation'. I'll be presenting a short talk on doc navigation best practices.

About the Write the Docs Conference

You can learn more about the Write the Docs Portland conference here: writethedocs.org/conf/na/2017/. The WTD conference differs from other tech comm conferences in a few key ways:

  • The attendees come from a wider swath of professions. It’s not just technical writers but also includes programmers, support, and other developer advocates too.
  • The cost of the conference is much less expensive than others ($450 for a corporate ticket).
  • There’s an emphasis on contributing to open source projects, with a writing day to precede the conference.
  • The talks are shorter (20 min.) followed by a 10 min. discuss period.
  • There aren’t a million parallel tracks going on at the same time.
  • There tends to be more emphasis on docs-as-code tools and workflows, since the founders are programmers.
  • All the talks are recorded and published on YouTube for everyone to watch.

My upcoming presentation

I submitted a talk about doc navigation and it was accepted. Here’s the abstract:

Building navigation for your doc site -- 5 best practices

Although users typically arrive at doc websites in a confused and impatient state, not sure of where to find what they're looking for, good navigation can guide them to the right answer. Good navigation anticipates users' needs, provides links in commonly viewed places, and brings the right topic into the foreground amid hundreds of other topics.

As you build out the navigation for your doc site, follow these best practices:

  1. 1. Use the doc homepage as a routing portal to let users choose the right doc set. Think of the home page as a train station with various terminals for departure.
  2. Include a navigation sidebar that contains a hierarchical representation of a group of topics. Right-size the group so that it's not too massive, nor too small, but rather provides meaningful at-a-glance context at a defined scope.
  3. Provide breadcrumbs above your topic titles that show the path to the topics. Assume that users may not arrive at the topic in the way you expect, and they will appreciate the context that breadcrumb provides.
  4. Provide abundant inline links in your sentences that help users navigate directly within the field of vision. Freely infuse links into phrases, words, or other parts of the sentence without always listing out the full title of the cross-reference.
  5. At the beginning of topics, add contextual links to orient the user. At the end, add next-steps links to guide the user's next decision. For sequences or tutorials spanning multiple pages, add workflow maps to make the user's progress in the sequence clear.

I know my presentation topic isn’t particularly clever or insightful, but there are large discussions within the tech comm community about the value of doc sidebars and inline links. Whether 20 min. will allow me to dig in deep enough or not, I’m not sure. At any rate, doc navigation (which informs findability and the user experience) surely makes up a huge part of the task of documentation.

follow us in feedly


Get new posts delivered straight to your inbox.

Subscriber count: 3,881

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.