What’s next for you in your career? It’s tempting to focus on the bare minimum — staying employed — but identifying new areas of professional development or focus can help you grow your career and find whatever enjoyment you can from the capitalist toil that is an obligation of modern life. While I was at Splunk, Susan St. Ledger gave a talk about approaching her career with a bucket list. I’d defined my career values, but a bucket list for my career was the perfect way to complement my career values while still growing my expertise. Even if you have the same title, you can have different exp ..read more

Docs as code is a much-vaunted workflow and toolchain for writing, publishing, and maintaining technical documentation — but in practice, docs as code doesn’t deliver on its promise. What is docs as code? According to the Docs as Code page in the Documentation guide for Write the Docs: Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code: Issue Trackers Version Control (Git) Plain Text Markup (Markdown, reStructuredText, Asciidoc) Code Reviews Automated Tests This means following the same workflows as development te ..read more

After I published Should you add screenshots to documentation?, I got some comments from folks who prefer GIFs to screenshots because GIFs can more clearly show how to use a complicated user interface. I agree that GIFs are cool and useful, but they’re also MUCH harder to keep up-to-date than screenshots and have extra accessibility considerations if you decide to use them. WCAG level A standard requires that: For any moving, blinking or scrolling information that (1) starts automatically, (2) lasts more than five seconds, and (3) is presented in parallel with other content, there is a mechan ..read more

Most web content is designed to display with a strict hierarchy, tree-based or otherwise. What if it wasn’t? What does it mean to display content as a graph? Why hierarchies are common Why use something different? Serve multiple mental models Write better documentation Improve content reuse Improve machine legibility Why don’t we display content as a graph? It’s difficult to design It’s confusing for readers It’s too flexible It’s difficult to write chunked content Sparse content and dense content don’t scale in a graph Visible graphs: The future of displaying content? What does it m ..read more

Heather Buchel’s post It’s 2023, here is why your web design sucks about the current state of web design (and web app design) resonated with me, especially this quote: “Design decisions can only be pushed so far to the left before we realize the system is broken” If you bisect design and development into different professions, you can end up with designers that aren’t technical enough to design what’s possible, or developers without enough design prowess to make design decisions independently. I wonder too if tooling has something to do with it — in an era of Figma and Canva and Webflow, it ..read more

As a tech writer, I’ve encountered a number of different processes that teams and companies have used to add documentation to their product development processes. Some of these are intentional and others are incidental—but all are used to create documentation across the software development industry. At its most basic, the product development life cycle involves the following steps: When you add documentation, that might look something like this: The typical models I’ve encountered working as a tech writer can be categorized as follows: The “throw it over the wall” model Advantages Disadv ..read more

It’s tough to find helpful information about analyzing website metrics for technical documentation sites. The goals of technical documentation are different from those of a marketing blog or a company website. You’re not optimizing for maximum traffic. No one is clicking “Add to Cart” on your API reference topics. You need to use slightly different metrics and in different ways than you might for a marketing blog or your company’s website. If you want to start using site analytics with your documentation but aren’t sure where to start, this post is for you. What are site analytics? Get a bas ..read more

Products use machine learning and “artificial intelligence” to do things like recommend a song to listen to, offer a quick response to an email, organize search results, provide a transcript of a meeting, and more. Some products rely on ordinary data analysis to construct insights about things like your business performance in a market, or the conversion rates for your online shopping site. Unfortunately, the companies providing these products often gloss over the technical details of how these systems work—making it seem like those tools are magic, omniscient, or just plain inscrutable. Algor ..read more

As a technical writer, I have a mixed opinion of chat applications like Discord and Slack. On the one hand, they make it easy to quickly get ahold of someone who can answer your questions, which is a relief if you’re struggling to gather information you need to write a draft. On the other hand, because it’s easy to quickly get ahold of someone who can answer your questions, that convenience can implicitly incentivize folks to neglect documentation. This is true on both sides: Folks with questions might ignore documentation that exists because it seems easier or faster to just ask in the chat ..read more

Matt Webb wrote a post about organizing data and mapping the experience of the web, and that made me consider how the decisions about documentation structure, especially in the early stages, require similar decisions. Technical documentation functions as a map for your product. For specific users, your documentation provides wayfinding guidance and provides the information necessary to navigate the space relevant to your product. Beyond a map for your product, technical documentation can also map out specific workflows within your product—specific routes, one might say. For example, diagrammin ..read more