Documentation is always a challenge. Not only does a team have to overcome the common aversion to writing it (and I hold my hands up as someone who finds writing docs not as fun as writing code), but there is also the struggle to ensure it stays relevant and up-to-date.
In the same way that data redundancy in a software architecture will constantly cause it's maintainers synchronisation headaches, as will syncing documentation of how code works with the code itself.
I have found that most docs relating to how code works in any sort of detail are doomed to quickly go out of date/sync unless they are inline with the code itself. Even with the best will in the world, people inevitably forget that particular docs exist to be updated.
Even if such docs are available and happen to be up to date, if I'm newly coming in to a project, past experience has taught me not to trust such documwntation too much (for the above reasons), and if you really want to be sure how some business logic actually works, you need to read the code.
So am I saying don't bother? No not at all. But I have found the best approach is to write code to be as self documenting as possible. Good naming and layout of code can help alot here. Where more explicit descriptions are needed code comments can be used.
Well written test suites are also a great way to not only ensure code does the right thing, but to describe what that is.
Where documentation outside of the code can be useful is in describing the high level concepts such as the system design and architecture. These have a fighting chance as they change less often and it tends to be a bigger event when they do. For Http APIs, libs that generate specs for tools like Swagger from the code are also very helpful.
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.
Documentation is always a challenge. Not only does a team have to overcome the common aversion to writing it (and I hold my hands up as someone who finds writing docs not as fun as writing code), but there is also the struggle to ensure it stays relevant and up-to-date.
In the same way that data redundancy in a software architecture will constantly cause it's maintainers synchronisation headaches, as will syncing documentation of how code works with the code itself.
I have found that most docs relating to how code works in any sort of detail are doomed to quickly go out of date/sync unless they are inline with the code itself. Even with the best will in the world, people inevitably forget that particular docs exist to be updated.
Even if such docs are available and happen to be up to date, if I'm newly coming in to a project, past experience has taught me not to trust such documwntation too much (for the above reasons), and if you really want to be sure how some business logic actually works, you need to read the code.
So am I saying don't bother? No not at all. But I have found the best approach is to write code to be as self documenting as possible. Good naming and layout of code can help alot here. Where more explicit descriptions are needed code comments can be used.
Well written test suites are also a great way to not only ensure code does the right thing, but to describe what that is.
Where documentation outside of the code can be useful is in describing the high level concepts such as the system design and architecture. These have a fighting chance as they change less often and it tends to be a bigger event when they do. For Http APIs, libs that generate specs for tools like Swagger from the code are also very helpful.