And the devs generally hate writing documentation.I can imagine. Moreso when they only finger type. Like me.
Just to make things clear, this is not a local phenomenon. As an industry veteran (since the late '60s and Fortran IV) I have always found that people who like to write code are concentrators, figurers, people who relate to the complexity of the machine--but not communicators. They want to convene with their code, not with people. Once the code is working they want to move on to writing more code. (Code is a drug. Docco is not.)
With some, the code is
the documentation. Live627 and I have been reading this docco. You read the code and you execute it in your head and go over it often enough and now the docco is in your head. Good for you, not particularly good for anybody else because we have not yet achieved telepathy.
My own personal style--in my career as hardware/software/firmware developer--was to include as much documentation in the code as possible. You could tell my assembly or C code anywhere because I filled up the right side of the page with detailed explanations of what was happening. I easily wrote as many comments as code (based on # of characters in a source file.) That was because I realized the comments were probably the best anybody would ever get.
I once spent several months doing nothing but playing second fiddle to another consultant who couldn't be bothered to write any docco at all, not even comments, and in some horrible test programming language (was it ATLAS?), so since their programmer consultant was their fair haired boy they hired me to do nothing but reverse-engineer his code and write the docco that was part of the customer's contract requirements. Must have docco. They were bad days for me but I got my rate, and my self-opinion of consultants, we are technology whores, we negotiate the rate and then my own personal credo, once we have a contract and a rate, I'll do anything I can to deliver the job for as many hours as I can clock.
But getting back to the point, people who write code do not like to document it, and people who do the documentation are usually separate from those who write the code. In an idea world the code writers would document everything they write. Sadly, at least globally speaking, that won't happen any time soon.
And specific to this or any open source project, developers change, and each developer leaving takes knowledge with them, each new developer has to figure it out all over again.
Mod package authors such as me are in a difficult position. Not working on the whole project we focus only on the features we are working on. Myself, I was absent for 3-4 years and a lot changed, except the code mostly looks so familiar. When I left integration hooks were relatively obscure (I had never heard of the then) but today they are all important, particularly because they make writing (and Mod Squad testing) of mod packages easier -- in both cases less code.
So far I've found docco on the hooks but only at a superficial level. I could benefit from examples, but my only examples force me back to reading the code, anybody's code, to reverse engineer how the hooks work.
So this gets back to that dichotomy: people who write code for the most part do not want to write docco. Most docco (in the universe, not specifically SMF) is written by reverse engineering.
I could easily fix this problem. All I would have to do is to change human nature...
Meanwhile I encourage and applaud all of those who contribute to SMF code documentation in any way. Thanks!