Best Practices for Effective Documentation Systems

Contributions

Every accepted correction to this page is recorded with the exact change, so readers can see how the page improved over time.

1. 29 July 2026 · corrected by Emir Baycan

   Removed unverified research statistics attributed to real researchers (Parnas/Clements, Redish, Wiegers, Arango) and unverified case-study metrics attributed to real companies (Stripe, Atlassian, GitLab, Basecamp); replaced with accurate, verifiable framing of each real source's actual work.

   Before

   Two sections ("What Research Shows About Documentation Systems" and "Real-World Case Studies in Documentation Systems") cited real people, books, and companies but attached unverified precise statistics to them: an unverified "73%" figure and unverified "rational design reconstruction" term attributed to Parnas & Clements' 1986 paper (whose real title is "A Rational Design Process: How and Why to unverified It" and which is a conceptual argument, not an empirical study); unverified 79%/68%/3.2 stats attributed to Janice Redish; an entirely unverified 2003 IEEE Software study of 47 organizations attributed to Karl Wiegers; unverified 64%/40x stats attributed to Jorge Arango; an unverified Stripe employee ("Ryo Chijiiwa, head of developer experience") with unverified 28%/34%/4.2-hours-to-47-minutes metrics; an unverified 2019 Atlassian internal audit with unverified 67%/41%/2.3-hours/71%/58% figures; unverified 12-day/28-day onboarding statistics attributed to GitLab; and unverified 64%/31%-to-9% statistics attributed to Basecamp's 2018 book (also misdated as 2019).

   After

   Both sections rewritten to describe only the real, verifiable substance of each source's actual work (Parnas & Clements' rational-reconstruction argument, Redish's scanning-behavior research, Wiegers' writing on ownership and staleness, Arango's work on findability; Stripe's task-oriented docs reputation, Atlassian's documented sprawl challenge, GitLab's real handbook-first practice, Basecamp's real write-once philosophy from Fried & Heinemeier Hansson's 2018 book) with all unverified statistics, names, and dates removed.

   Why: Independent verification via two research agents found zero of the eight cited studies/statistics were locatable in any real published source; all eight paired a real, checkable entity (person, book, or company) with unverified precision numbers, a pattern consistent with prior findings across this fact-check project.

   View the full record →

Contributors In This Page