Documentation is the unloved step-mother of software development: Nobody likes it.
On the writing side, documentation is either considered a waste of time:
- I could write code in that time
- It won’t be valid anymore after the code changes tomorrow, anyway
- There is no way to make sure you can trust documentation
- Stringing sentences is hard work, especially when you want to make them easy to read, understand and interesting to follow.
- It’s hard to connect code samples with documentation
- If I describe too many details, readers will be bored. If I omit too many, they will be confused. There is no way to know which level of detail is good.
On the reading side, it’s a waste of time:
- I need to solve a problem, I don’t have time to search in a huge dump of text
- If the author doesn’t trust the documentation, how can I?
- It will contain too many details that I already know and omit too many facts that I need to understand what is going on.
The core of the issue is that documentation and code are two different things. Documentation is, by nature, abstract. It’s at least one step removed from the solution.
Does it have to be that way?
So instead of writing hundreds of lines of code to open a window, give it a size, make sure it remembers its size and position, etc., we could write:
Users can search for Customer objects by any of the name fields.
Note that the links are part of the documentation and the code; the underlying code generator should follow them and examine the code/documentation on the other side.