In software development, how much documentation do you need?
My answer: Just enough.
I do not hate documentation, I am actually pretty good at ...
For further actions, you may consider blocking this person and/or reporting abuse
It's been my experience that people are happy to dump information into a wiki but many will rarely, if ever, update it or clear out obsolete parts.
I'm not really sure what to do about this part short of trying to make it as easy and light-weight as possible to do, and I suspect (but haven't tested) that the best solution to this is wikis based on a VCS where the users can download all the files to their own system, and use their existing local file editing tools, rather than a web interface.
Confluence in particular seems very heavy to me since Atlassian removed the markup interface and made it all use the rich-text editor.
A process that could help with wiki-based documentation would be to have every single article on the wiki automatically marked as out of date on some regular schedule.
Active articles would quickly be edited and acknowledged as up to date, whereas abandoned articles would either be removed or left marked as out of date.
This sounds like a good idea, at least to start from.
I've also considered something like a bot that would give people "A Doc a Day" -- mailing people a single page that they can then either update, delete, or mark for a more involved look.
Delivering software being system component, more engineering level documentation is often expected. Customers/peers will request: requirements/features list, overall high-level architecture, explanation behind design decisions, API description, various reports: performance reports, test coverage report.
Requirements regarding documentation differ from one industry to another. Unfortunately, there is no general rule how much is enough.
If you're delivering an API then one would expect the API to be documented. However, if you're delivering code then the expectation should be different. That is, there's no implicit requirement to produce extensive docs just because you have a code deliverable.
The software industry is immersed in other industries. The product is not always a complete, end user facing, application or system. We are delivering parts of a solution and it is necessity to explain an idea behind the code. This enables other engineers to create more efficient systems.
What is more, I do not expect to receive a full blown word document each time. Describing simple algorithms in few sentences of a readme, uml diagram or presentation is often enough.
Providing an explanation why we did things certain way is a part of engineering work.
I agree with this. Code documentation is best reserved for things that aren not self-explanatory in the code. They are also only a second resort, when refactoring doesn't fix the problem.
Documentation is however good for cross-module, or highly abstract, concerns in the code. Sometimes the flow of the code just doesn't capture the big picture. Comments on the big picture can help somebody new to the code. It tends not to get as outdated as quickly either, since the high-level concepts change at a slower pace.
As an expception, if the deliverable is a library, one would expect the API to be extensively documented. The users of the library shouldn't be expected to read the source to understand how to use the API.
The importance of that paragraph. Internal documentation all of this is spot on.
Externally, if your users have to work, forget getting them.
Absolutely!
Shameless plug (but totally relevant!): Please have a look at codestoryapp.com. It was designed to address what I think are the main issues of code documentation.
For me, unnecessary documentation is an overkill. If a code speaks for itself, there isn't a need to document it.