On the beginner-friendliness of scientific libraries

It is hard because we don’t understand what the user needs and which structure should have a doc, and how to start. Diátaxis is answering those questions. And when you have understood, it is more fun to write a doc!

Most of the time, you will find libraries where the “Reference” quadrant is overwhelming, as it can be (relatively) easily automatically generated by tools like FORD or Doxygen. And the poor beginner feels overwhelmed… (three big letters are falling on his/her head: A P I :boom:)

And writing documentation can be undervalued and coding considered to be more important. But not always, for example in the FreeBSD community people writing doc are considered as important as those coding, and that is why the FreeBSD is very good: