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.
About Tom Johnson
I'm a technical writer based in the San Francisco Bay area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.