Software documentation is the collection of written descriptions that explain how a system works and how to use it, including inline code comments, user guides, API references, design documents, and README files. Good documentation makes software understandable, usable, and maintainable by both current and future developers.
Documentation is the label on a medicine bottle: what it is for, how much to take, what not to mix it with. The pills work without the label, but nobody can use them safely. And like a label, it is only useful while it matches what is inside; a wrong label is more dangerous than a blank one.
Showing a random 20 of 50 problems.
Example 1
challenge
Your team has 50 open-source consumers of a library. You plan to deprecate a function in 6 months. Design a 4-step documentation rollout to minimize user breakage.
Example 2
challenge
A team writes thorough docs once at launch but never updates them; six months later many are wrong. Name the failure and the disciplined fix.
Example 3
medium
Which comment is more useful: (a) `// loop over users`, (b) `// skip suspended users to avoid sending re-engagement emails to banned accounts`?
Example 4
medium
A function's docstring lists parameters but omits that it returns null on error. What documentation principle is violated?
Example 5
medium
After a refactor, the README still shows the old command name. What is the defect and the fix category?
Example 6
easy
Good documentation explains code's ___ and how to use it, not just restating syntax.
Example 7
medium
A comment says '// returns true' but the function returns the count of items. What should be done?
Example 8
medium
A new teammate needs to understand WHY a module exists and its overall structure, not call signatures. Which doc fits best?
Example 9
hard
Argue both sides: 'Good code is self-documenting and needs no comments.'
Example 10
hard
A team writes docs only after shipping. Suggest one process change that ties doc writing to code merging.
Example 11
medium
For an end user (non-programmer) learning to use the app's features, which doc fits best?
Example 12
hard
You inherit a 5,000-line module with no documentation. Outline a triage approach to document it without rewriting everything.
Example 13
medium
A function has no comments or documentation. Reverse-engineer its purpose from the code: FUNCTION mystery(text): SET result = ''. FOR i = LENGTH(text)-1 TO 0 STEP -1: result = result + text[i]. RETURN result. Write appropriate documentation for it.
Example 14
easy
Which comment is BETTER: (a) 'x = x + 1 // add 1 to x' or (b) 'x = x + 1 // advance to next page'?
Example 15
easy
Documentation primarily serves which audience?
Example 16
medium
Fill in the blank: good documentation explains the ____ of the code, not just restates its syntax.
Example 17
hard
A documentation site needs to explain 'how do I do X?' for a specific task. What Diataxis category is this?
Example 18
hard
An API's docs list every parameter but never give an example. What is the main risk?
Example 19
medium
A function has comments only for the success case; it can also throw on invalid input. What documentation gap exists?
Example 20
easy
Inline notes inside source code that explain logic are called what?