Emmanuele Bassi is a developer of the GTK project, whose answers on the GNOME Discourse are always very helpful, with very clear arguments.
The documentation problem is of course not specific to Fortran, but is important for the success of a project, open source or not. The Fortran community can use this post to discuss about it. Share here your opinions and experiences about documenting your projects.
Uh, fully agree developer documentation is really hard to get right. I guess many of my projects are lacking a lot on this side. For most of them I’m not really sorry for haven’t invested time there, but for some I would really like to have a straight-forward way for a new developer to on-board, without requiring them to learn all things the hard way.
I can see that a contributing guideline, style recommendation and design rationale document might be a first step, but beyond that I’m not sure what is needed as a kind of knowledge base to make a project sustainable.
I’d be interested to learn and explore ways on how to improve here. Maybe projects like fpm and stdlib, as larger collaborative projects, are a good sandbox for trying out different ideas of building a developer knowledge base?
There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation , there are four.
They are: tutorials , how-to guides , technical reference and explanation . They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most documentation - often immensely.
As you may know, the fpm doc and stdlib doc use the Diátaxis method developed by Daniele Procida. He has worked as a Django developer and is now working at Canonical (Ubuntu) to evolve its documentation.
In this inspiring Write the Docs 2021 conference, entitled “Always complete, never finished”, he explains how to use efficiently Diátaxis to document your new project or to restructure an existing documentation:
