/Documentation

Developers Don’t Need More Documentation

- Dennis Pilarinos tl;dr: Docs get written, but answers stay hard to find. The problem isn’t the docs themselves. It’s that the context developers need is scattered, outdated, or missing entirely. Why does this keep happening? And what’s the alternative?

featured in #623

Adopting Docs-As-Code At Pinterest

tl;dr: “We began exploring different approaches to enhance our documentation tools and processes, with a particular focus on the docs-as-code strategy. This initiative aimed to not only elevate the quality of our technical documentation but also to transform the culture of documentation at Pinterest. The result was PDocs, our internal documentation system.”

featured in #622

Developers Don’t Need More Documentation

- Dennis Pilarinos tl;dr: Docs get written, but answers stay hard to find. The problem isn’t the docs themselves. It’s that the context developers need is scattered, outdated, or missing entirely. Why does this keep happening? And what’s the alternative?

featured in #617

Developers Don’t Need More Documentation

- Dennis Pilarinos tl;dr: Docs get written, but answers stay hard to find. The problem isn’t the docs themselves. It’s that the context developers need is scattered, outdated, or missing entirely. Why does this keep happening? And what’s the alternative?

featured in #615

Developers Don’t Need More Documentation

- Dennis Pilarinos tl;dr: Docs get written, but answers stay hard to find. The problem isn’t the docs themselves. It’s that the context developers need is scattered, outdated, or missing entirely. Why does this keep happening? And what’s the alternative?

featured in #608

Why Documentation Fails Developers

- Dennis Pilarinos tl;dr: Developer documentation is a paradox. Teams spend hours writing it, yet it’s often outdated, incomplete, or hard to navigate. But the solution isn’t writing more or centralizing documentation—it’s surfacing the context where developers need it.

featured in #606

Summarizing Our Recommendations For Software Documentation

- Nicole Tietz-Sokolskaya tl;dr: A software engineer and anthropologist conducted a case study on engineering documentation practices. Their key recommendations include starting with high-level docs, implementing design reviews, considering audience needs, maintaining docs as part of workflow, and documenting test plans. The study involved literature review and engineer interviews, revealing how documentation practices reflect and reinforce company values.

featured in #589

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