/Documentation

What Makes Documentation Good

- Ted Sanders tl;dr: From the team at OpenAI: Make docs easy to skim, write well and be broadly helpful. Starts with: (1) Split content into sections with titles. (2) Prefer titles with informative sentences over abstract nouns. (3) Include a table of contents. (4) Keep paragraphs short. (5) Begin paragraphs and sections with short topic sentences that give a standalone preview. (6) Put topic words at the beginning of topic sentences. (7) Put the takeaways up front. (8) Use bullets and tables. (8) Bold important text.

featured in #540

Tied Up In Docs

- Luke Abel tl;dr: “We want to document decisions, and we know when, but what do we actually write? Here, too, I like to keep it lightweight. A decision record should contain, at a minimum: (1) Some context or problem. (2) A decision made in response to it. Assume your audience is proficient, but lacking context – that’s why they’re reading!”

featured in #527

The Documentation Tradeoff

- Kent Beck tl;dr: “In the end, write the docs you want to write. If no one reads them, or if readers find they are out of date, then consider not writing them next time. But don’t let anyone shame you into wasting time. The question is not, “Do you have documentation?” but rather, “Do you communicate clearly?””

featured in #524

Summarizing Post Incident Reviews With GPT-4

- Wuji Zhu tl;dr: "We start by fetching the report from Confluence and parsing the HTML to extract the content of the PIR as raw text. We then remove sensitive data, including links, emails, and Slack channel names, to avoid exposing internal information to public models and ensure blameless summaries. We then send the text version of the report to GPT-4 chat completion to generate a summary." This is then archived with additional metadata and summarized onto the Jira ticket. Wuji provides an overview of how this is operationalized. 

featured in #468

My Problem With The Four-Document Model

- Hillel Wayne tl;dr: Hillel critiques the 4doc model for user documentation, highlighting that it's not universal or comprehensive. While effective for tools, it may not suit frameworks and languages. The key takeaway is that relying solely on the 4doc model can limit documentation effectiveness, and a more flexible approach that considers the specific subject being documented is encouraged.

featured in #438

Motivating Developers To Care About Documentation

- Paulo André tl;dr: Ask yourself why you need documentation e.g. making better decisions across the org, helping people get the right information, making onboarding more self-service. "If we’re deciding whether to write something, we should ask whether writing it will help us with one of those objectives." Paulo suggests pointing your team towards the "why" and also provides tips for maintaining the practice.

featured in #309

Notes On Technical Writing

- Marcus Kazmierczak tl;dr: Marcus frequently writes documentation for Wordpress. Here, he guides us through some of his learnings, including the concept of Minimalist Instruction.

featured in #169