Recording of my WTD Portland 2017 presentation on Building navigation for your doc site -- 5 best practices

Here's the recording of the presentation I gave at the Write the Docs 2017 Portland conference. The presentation explores best practices for doc navigation, including principles such as hierarchy, modularity, progressive disclosure, entry point, and wayfinding. The presentation is about 20 minutes long, and you can either watch a video or listen to audio. Other WTD presentation recordings are also available. Read more »

Write the Docs Podcast Episode #6: Metadata and UI copy

In episode 6, we explore the role of metadata in documentation and how it can be used to classify topics and assist in the discoverability of information. We’re joined by special guest Eva Jackolis who explains a strategy for metadata used in German mechanical engineering documentation. We also discuss involving tech writers in UX copy and the challenges inherent in influencing UI copy, product naming, and working with UX designers and product teams. Read more »

Limits to the idea of treating docs as code

If there's been a theme for the past year in tech comm, it's to treat docs like code. Most people get behind this idea with a great amount of enthusiasm. And yet, in many ways, docs are not entirely like code. You can make processes a lot more complicated if you push the the docs-as-code idea to the limits. Docs differ significantly from code when it comes to release frequency, release complexity, review processes, and company support. Read more »

How big should your documentation repo be?

How big should your documentation repo be, especially if you have multiple products in your documentation? Although you could put all content into the same repo, it might be easier to have lots of little repos. Jekyll accommodates this architecture quite nicely through gem-based themes. Read more »