I’ve seen bug reports and Slack conversations that start like this:
@blacktshirt1981:
‘I tried to use your library to decode the integer 1 to a boolean and it crashed. Please document that your library doesn’t decode integers to booleans.’
I probe a bit in my response:
@jessewilson:
‘Oh darn, lemme fix. Which docs did you read? (I want to update the right ones!)
And predictably the documentation-requester might not be a documentation-consumer:
@blacktshirt1981:
‘Nothing specific. I just think it’s worth documenting.’
The root cause of the docs complaint is ‘I don’t understand it’.
I can address the request by writing some documentation. But sometimes the best way to make a project easier to understand is to change the project itself:
- Remove non-essential components
- Find components that do too much, and decompose ’em
- Find components that do too little, and combine ’em
I prefer a simple solution over a well-documented complex one.