Write the Docs Podcast Episode 2 (which Focuses on Findability) Now Available
You can view the Write the Docs podcast here:
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.
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.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.
About Tom Johnson
I'm a technical writer based in the California San Francisco Bay area. In this blog, I write about topics related to technical communication — Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, academics, and more. I'm interested in simplifying complexity, API documentation, visual communication, information architecture and findability, and more. If you're a technical writer of any kind (progressional, transitioning, student), be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.