Documentation in the Era of Concepts and Ranges
summary
Compares current docs (Abseil, fmtlib, LLVM, Catch2, range-v3, Boost.Range) and recommends concrete changes: put a short description and an example at the top, list type requirements, pre/postconditions, construction patterns, reference type, range category, const/borrowed behaviour; treat concepts as interface-level checks and use concepts as documentation tool so compiler errors become precise. Use tests as executable examples, prefer prose-driven web pages over raw Doxygen, be explicit about maintenance costs for handwritten docs and link diagnostics to docs for clearer compiler guidance.
AI-written summary · about
chapters (31)
- 0:00Start
- 1:06Agenda
- 1:35Disclaimer
- 2:28Categories of Documentation
- 3:05Internal Apis
- 4:51Goal Oriented How-To Guides
- 5:15Understanding Oriented Discussions
- 7:15Documentation in the Header
- 7:44Format Lib
- 9:57Cache2
- 11:55The Library Range V3
- 14:17Range V3s Tests
- 15:03What Good Documentation Is
- 15:15What Is Good Documentation
- 16:16Know Your Audience
- 16:27Clear Documentation
- 18:17Learning-Oriented Tutorials
- 23:11Accessibility
- 30:54Measuring Your Documentation Quality
- 31:43What Is a Concept
- 34:41Compiler Error
- 40:31Documenting Ranges
- 46:42Lazy Split
- 49:06Construct a Range Arrange Object
- 53:20Clarity
- 58:58Handwritten Documentation
- 59:29Chunk by Key View
- 1:00:34The Reference Type
- 1:04:00Rust Error
- 1:08:50How Do We Feel about the Rust Documentation
- 1:12:33Contracts
related talks
01h 02m“How to Write Effective Documentation for C++ Libraries..."
01h 24mWriting Documentation - Practices and Theory
35mThe practical implementation of Documentation as Code
35mThe struggle for better documentation for Ruby itself
16mcod == doc
46mSave a Dev, Write Documentation!
41mStop making fool of yourself about documentation
18mContinuous Documentation Manifesto