Write the Docs Podcast Episode 2 (which Focuses on Findability) Now Available
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.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.