If you need documentation probably you are not writing good code.
Documentation is absolutely needed when writing third party libraries, but everyone of your team should know all the aspects of the codebase, at least at high level.
If someone doesn't know it then documentation is not the solution.
Doing some pair-programming, adding them as reviewers of more pull requests, writing some wiki page that explains the architecture of the various components are much more effective ways.
Remember that documentation is not free, you need to spend a certain amount of time to build it and even a greater amount of time to maintain it.
Every time that I've seen some attempt at writing documentation in javadoc or whatever is called in .net, there were always missing parameters in the methods, wrong arguments and method names, parameters not existing anymore and so on.
Naming is also a very important aspect.
Just yesterday I found in a pull request something like "SingleLineTextBoxTextTooLongShowTooltipHandler".
This doesn't really add any information and just makes it impossible to understand what is meant to do.
I proposed to change it to "TextOveflowTooltipHandler", maybe still not ideal, but I think that is a definite improvement over the original.
DSLs in theory should be self documenting.
Gherkin is quite easy even if you don't read the documentation and even if you don't write code.
If on the other end you write some Lisp-esque ultra compact DSL that has no whatsoever connection with the real world then also in that case the best solution is not to write the documentation, it should be to write a better DSL.
> Doing some pair-programming, adding them as reviewers of more pull requests, writing some wiki page that explains the architecture of the various components are much more effective ways
You get a new member of the team, how do pull-request reviews and pair-programming help them get familiar with old code? Documentation is a way of stating explicitly what might be learned implicitly from those tasks.
> Every time that I've seen some attempt at writing documentation in javadoc or whatever is called in .net, there were always missing parameters in the methods, wrong arguments and method names, parameters not existing anymore and so on
So fix that. review the comments as part of code review - if the documentation is in the code this should be easy. From my memory of Java, doesn't eclipse have some sort of doc sting checker? I'm sure I recall the in-comment parameter names changing when you updated the method name...
DSLs in theory should be self documenting. Gherkin is quite easy even if you don't read the documentation and even if you don't write code. If on the other end you write some Lisp-esque ultra compact DSL that has no whatsoever connection with the real world then also in that case the best solution is not to write the documentation, it should be to write a better DSL.