Documentation has this nasty problem of becoming outdated. It can be infuriating to have stale documentation. It's often worse than having no separate documentation at all.
Agreed 100%. That's why I propose documentation be updated before you write that new feature or update. More often then not, developers forget to update the documentation after the update's been pushed.
Docs should be left for high level things that don't change often, like the overall architecture, or module descriptions.
Also agreed! I guess it wasn't clear in the post but I didn't say you have to document every nook and cranny in the code. What I was saying, in the excuse section, was that documenting within the code is not a valid excuse to not have proper standalone documentation. In an ideal world you would have both good high-level documentation and accurate docblocks.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Agreed 100%. That's why I propose documentation be updated before you write that new feature or update. More often then not, developers forget to update the documentation after the update's been pushed.
Also agreed! I guess it wasn't clear in the post but I didn't say you have to document every nook and cranny in the code. What I was saying, in the excuse section, was that documenting within the code is not a valid excuse to not have proper standalone documentation. In an ideal world you would have both good high-level documentation and accurate docblocks.