How is it done in practice to maintain a project documentation but not the documentation to the users but the doc for the maintainers. For example, is it customary to just look at the files and understand how it works or we should have class diagrams, etc to explain the project? I don’t see any project on Github having class diagrams.
Isn’t it bad practice to reason about the project structure and classes directly on the code rather than on diagrams?
I do not think this is a full answer, however…
Documentation has a tendency to be obsolete. If comments, which are right there in the code, become obsolete because a developer forgot to update them, now imagine a class diagram that sits as a separate file.
The best documentation you will find is generated by tools from the source code, and usually comments. And yes, some of that generated documentation is can be in the form of class diagrams.
There are tools such as Doxygen and Document! X and other alternatives.
With that said, a large portion of github projects are maintained by a single person or a small group, done for free on spare time… there their priority is on getting something working… every time there is an opportunity for documentation there is also an opportunity to fix a bug or a add a requested feature.
Because of that, you will find the best documentation on medium to big projects, where they have donations or some business model from where they get the money to hire developers… and it is somebody’s job to set up the documentation and make sure it is complete and stays up to date.
When there is a person with the responsibility of making sure the documentation is being generated, that is has examples, and that they work… and you know development will contiune marching on despite this person being busy dealing with the documentation (because there are plenty of developers involved in the project)… then it is more likely you will have good documentation.
Alternatively, if there are a lot of people involved in the project, it can be done as a community effort, for example in the form of a wiki.
Again, it is not that a single developer or small team can’t do it. Just that they are less likely to do it, because it nevers feels like it is a priority.
Besides, they are the only ones dealing with it – again, usually in spare time – so better have clean readable code, than write documentation for other maintainers that do not exist… and yes, having that documentation (among other things) could make it easier to have more maintainers.
By the way, on the topic of class diagrams… if we are planning something, we can sketch it and share it by other means other than put them in the repository… (attach it to a shared kanban board, for example). And if we are trying to understand the system, we can run a tool that generates it from the code, thus no need to put it on the repository either.
Errata: OK, you could have them in site associate with the project, probably generated as part of continuous integration.
I’d like to suggest an interesting reading resource: https://leanpub.com/livingdocumentation
Furthermore, I only value documentation that is written for developers as if it were user documentation. How-to-use guides, written in a wiki or in a markdown readme. In that regard I disagree that there is no documentation on github. In fact, the only way to get other developers to use your open source tools is by having a comprehensive readme with clear examples.
The nitty-gritty of how classes interact or which methods they have is useless. I have an IDE for that.
If there is something unusual going on with some method, or if there is some intelligent algorithm doing magic, I will always add as many lines of comment as required. But only in the code.
The architecture of a project I would only document on a high level. Maybe write down how you handle storing or fetching data. But all that I can also see from looking at the code, so this might only be required if you need something to scold lazy programmers with.