Good documentation is nice but there are reasons why it rarely exists. This is not just a matter of laziness.
In order to write good documentation, you have to fully understand what you are doing. This is often not the case in software development. More often than not, people don't fully understand the requirements (which is of course also a documentation issue) or they get something working or accepted by copying or pasting code they do not fully understand or by doing some other kind of voodoo. I don't say that this is a good thing in the long run or that it is unavoidable but it often seems to be efficient from a business point of view.
Even if you know what you are doing, it is extremely hard to document it in a way that really helps others. Unfortunately, much of the documentation I have read, falls into one of the following categories - and that's surely not because the people who wrote it were stupid:
Somebody has put a lot of effort in it, it is nice to read, maybe with many sketches and screenshots, but you don't find what you are actually looking for. You still have to check the source code.
Somebody has put even more effort in it and explains everything completely and exactly. It is hard to read and understand, maybe harder than reading the sources. You spend a lot of time on it. Still you are not sure if you got it right and have to double-check it by looking at the source code.
And this is maybe the most important point: Software changes over time. It is extremely hard to keep external documents in sync with it.
Again, good documentation is really nice. Unfortunately most of the documentation that exists is not too helpful in practice, even when it has been written by intelligent and competent people. We typically think that we can do it better but it is really hard and might not be worth the effort.
Don't get me wrong, this is not meant to be pessimistic. I am describing the current state of affairs and am sure we can do better in the future. But this will not be easy to achieve and cannot be accomplished with a little bit of motivation. It will probably involve tools that automate part of the process.
And this is maybe the most important point: Software changes over time. It is extremely hard to keep external documents in sync with it.
This is one of the most important points. When you develop, you estimate the effort contemplating the documentation you will have to change. It's basically the same with tests:
Good point, documentation updates need to be planned, otherwise they will probably not happen at all.
But that does not change the fact that they can cause a lot of overhead. A simple feature that is quickly implemented can require many documentation changes in multiple documents. It is far from being trivial to find all the places that need to be modified in natural language documents. Things get worse when you work in a larger team where multiple changes are implemented simultaneously.
There are approaches like ALM (Application Lifecycle Management) that promise to resolve issues like that. But so far I found all ALM systems to be hard to set up and use.
Updating tests is less difficult because a test will tell you that it needs to be updated, simply by failing - assuming that the change is implemented correctly. Unit tests are even less critical because they are closely related to the code that has been modified.
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.
Good documentation is nice but there are reasons why it rarely exists. This is not just a matter of laziness.
Again, good documentation is really nice. Unfortunately most of the documentation that exists is not too helpful in practice, even when it has been written by intelligent and competent people. We typically think that we can do it better but it is really hard and might not be worth the effort.
Don't get me wrong, this is not meant to be pessimistic. I am describing the current state of affairs and am sure we can do better in the future. But this will not be easy to achieve and cannot be accomplished with a little bit of motivation. It will probably involve tools that automate part of the process.
This is one of the most important points. When you develop, you estimate the effort contemplating the documentation you will have to change. It's basically the same with tests:
Effort For Feature = Documentation Effort + Implementing Effort + Testing Effort
For every Effort you ignore, troubles will arouse, one way or the other :)
Good point, documentation updates need to be planned, otherwise they will probably not happen at all.
But that does not change the fact that they can cause a lot of overhead. A simple feature that is quickly implemented can require many documentation changes in multiple documents. It is far from being trivial to find all the places that need to be modified in natural language documents. Things get worse when you work in a larger team where multiple changes are implemented simultaneously.
There are approaches like ALM (Application Lifecycle Management) that promise to resolve issues like that. But so far I found all ALM systems to be hard to set up and use.
Updating tests is less difficult because a test will tell you that it needs to be updated, simply by failing - assuming that the change is implemented correctly. Unit tests are even less critical because they are closely related to the code that has been modified.