Adobe Robohelp

Get new posts delivered straight to your inbox.

Subscriber count: 3,589

Stitcher radio

follow us in feedly

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

Adobe Robohelp

Write the Docs Podcast Episode 2 (which Focuses on Findability) Now Available

Dec 18, 2016 • general

Episode 2 in the Write the Docs podcast is now available. The topic of episode 2 is findability: How do you allow your users to find what they're looking for in your documentation? We talk about various tools for findability: search, tags, faceted filters, sidebar navigation, inline links, related links, terms/glossaries, and breadcrumbs. In this post, I also share a few more details about Lunr search.

You can view the Write the Docs podcast here:

You can also go to the WTD podcast site to view it: Episode 2 - Findability.

Why did we choose to talk about findability? Besides the fact that it’s a recurring theme in tech comm, recently someone contacted me with this exact question. They wanted to increase the ability for users to find what they’re looking for in their documentation.

I have a lot of thoughts about findability in documentation. I once wrote a lengthy series of posts on organizing content and have presented numerous times on findability (see Making Content More Findable When Users Browse and Search.) The topic has a tremendous number of angles and depth.

In the beginning of this podcast episode, we talk a lot about search tools. Search is an increasingly difficult component if you’re working with a static site generator like Jekyll for your authoring tool. Static site generators typically don’t include search features, so you have to figure out the approach you want to take.

You can integrate third-party search such as with Swiftype or Algolia, if you’re okay with hosting an index of your content on a third-party server and paying approximately $300/month.

While I’d love to use one of these services, it’s difficult to get security approval, budgetary go-ahead, executive buy-in, and other corporate processes aligned to make this happen. I think doc teams are accustomed to having their help authoring tool provide the search out of the box.

I’ve been working on a new version of my documentation theme. In this version (still under development), I implemented Lunr search by following this excellent tutorial by Mike Neumegen from CloudCannon here: Jekyll Search Using Lunr JS.

In our WTD podcast discussion, Jared said for large sites, Lunr search might not scale. However, I’ve chosen to implement Lunr a bit differently. In my doc theme, you can do either a global search or a product search. The global search looks across all doc pages, while the product search looks for doc pages within a specific product.

The idea is that with a more limited subset of content, Lunr search might be adequate.

To configure Lunr search, you loop through the pages you want and push them into a variable that Lunr uses to execute the search against. The content is stored in JSON, and you can boost certain values with more weight. I’ll provide more details when I release the next version of my doc theme, but overall I’m excited about it.

If you like to listen to podcasts, be sure to subscribe to the Write the Docs podcast. You can subscribe through email, RSS, iTunes, Stitcher, or Youtube. See How to Subscribe for more information.

follow us in feedly


Get new posts delivered straight to your inbox.

Subscriber count: 3,589

Powered by ZipRecruiter

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.