“How to Write Effective Documentation for C++ Libraries..."
summary
GitHub survey data (5,500 respondents across ~3,800 projects) shows 93% frustrated by poor docs; the claim is that writing docs alongside code catches design holes early and reduces scope creep. Demonstrates a concrete ring_view adapter example with push/pop, uses a compilation-time guard (TICK_TRAIT_CHECK is_forward_iterator) and targets C++11; shows how referring to standard concept pages avoids reauthoring type requirements. Compares tools: Doxygen (auto-sync refs), DocBook/QuickBook and XMLmind (structured narrative), and explains tradeoffs.
AI-written summary · about
chapters (8)
- 0:00Introduction to documentation pain
- 7:34Documentation in parallel with code
- 10:44First sentence clarity matters
- 21:07Writing code with documentation in mind
- 32:20Structure of effective documentation
- 45:56Tools and their limitations
- 53:34Recap and key takeaways
- 1:00:25Q&A on documentation practices
related talks
01h 24mWriting Documentation - Practices and Theory
01h 15mDocumentation in the Era of Concepts and Ranges
30mA Documentation Talk
46mTechnically Speaking: Improve your code with documentation
20mThe Curse of Documentation
29mHumanizing Your Documentation
44mHumanizing Your Documentation
52mTechnically Speaking: improve your code with documentation