At first, I thought that the people writing the code should also document it. But there are reasons why this might not be true. A person who is new to the code could ask the right questions which might be dismissed as "obvious" by the author.
My question is if there is an established practice (or practices), and what is the reasoning behind it/them?
It sounds like you're making the assumption that the documentation is written once and never updated. That may be true if your software never changes after it has been written, but that's probably not the case. Just like you can refactor your code to improve readability and maintainability, your documentation should also be in a format the promotes the ability to refactor. Your initial code authors are good candidates to write the initial documentation, but the people who maintain the code will also need to maintain the documentation. If the existing authors are still around and are answering questions from the new maintainers, someone (either the original authors or the new maintainers) should be assigned the task of making sure that the documentation is more complete.
The exact breakdown of roles and responsibilities depends on the organization. In some places, the developers are responsible for anything in the code file (API documentation and in-line comments) and the developers and testers support technical writers who write and maintain documents. In other organizations, the development team may write everything.
At the end of the day, it doesn't really matter who writes and maintains the documentation, as long as it is maintained. After all, wrong documentation is quite possibly worse than not having documentation at all.
In my experience the biggest problem with documentation is that it often does not paint the picture that matters, that lays out a high level model and then zooms in. If you let developers write documentation you get a repetition of code in natural language which is utterly pointless to both other developers and users alike. Documentation should be written in the course of analysis and design by analysts and designers, not as an afterthought by those who typed in the code. If you are lucky it is all the same person who is not too authistic and has some imagination. Unfortunately documentation is often something someone has to do before the project may be flagged as done.
And yes, it should be revisited which could be done by developers but the framework should already be there, created by people that know the why, the where from and the how rather than just the what. It is all about context, providing references to newcomers they can build their understanding on.
Should developers or other people write (technical) documentation?
It depends:
A quote from ReadTheDocs Documentation Principles:
"In the documentation process, include everyone from developers to end users.
Integrate documentation into the standard workflow of developers, and seek to reduce silos that solicit documentation from only a subset of the software’s contributors. Developers and engineers are the people with the best access to in-demand information, and getting them to document it will help foster a culture of documentation."
Some other points:
In any case, a collaboration of several people would be better than one person. If you write documentation with the same tools as the software, you might have a review process for reviewing the docs as well as they are being submitting as pull requests / merge requests.
Decide on the source of the documentation (e.g. Markdown, reStructuredText etc.) and a toolchain for contributing. This will make it possible for several people to work on the documentation and keep it up to date. Some projects keep the docs source in the same repo as the code. Example (SaltStack: docs are rendered on https://docs.saltstack.com/, are written in reStructuredText (.rst) and can be edited via "Edit me on GitHub", source is in GitHup repo https://github.com/saltstack/salt/tree/master/doc)
If you have several people documenting (and in any case), it is advisable to put down some ground rules. This will prevent unnecessary discussions and make the documentation more consistent. This is often done in the form of a style guide. The style guide should addresses points such as:
The original developer is in the best position to write technical documentation, but there are reasons why they wouldn’t:
The developer produces excellent code and rubbish documentation. Then it is better for everyone involved if they spend their time to write excellent code, not rubbish documentation.
Hiring a person to write the documentation may be cheaper, and doesn’t slow down production of code.
Personally I like to have developers/engineers write and explain with other technicians in mind. So that they and or others in their gebit would be able to understand and continue the work a few years later ... Preferably following some styleguides, but it is more important that it mentions necessary things than that it looks good. Then have a technical writer or others more specialized in explaining/visualising but together tutorials/guides etc for either "non technical end users" or more "correct/formalized" document archives.
