It isn’t very difficult at all, especially in software systems. One tries to make sure that it is easy to skip introductory material when looking at reference material and one is largely done.
I’ve seen the excuse that “well, an experienced user of the system would be slowed down by seeing that explanation”, but usually this is a false economy, as experienced people can skip to more or less just what they want. (We live in the modern world, and people typically use search and hyperlinks to read things, they don’t read them every time on paper.) See also below my comments about Unix man pages.
I think as evidence for this we can see that the documentation for a number of modern systems meets these criteria, and is clean, clear, and easy to read. The fact that others succeed at it means it is not impossible to do.
A happy medium exists between this and certain “documentation” I’ve seen for functions in certain libraries that is barely more than the type signature and a single sentence that explains neither the use nor the motivation for the existence of a function.
Often having just three sentences, or even two, solves such a problem, but I’m aware some people insist that they’re “attempting to cultivate a certain mindset in the reader” and other such rot and outright refuse to have their documentation explain things like motivation or purpose. They fight pitched battles to avoid having a function documented with two or three sentences instead of one! This is not “re-explaining the world”, this is just simple courtesy to your users. Often even an extra phrase here and there will save people time when trying to figure out how something works.
At one time, I was a newcomer, and I found the OCaml documentation opaque. I am now someone who has been using the language quite steadily for a year, and I still sometimes find the documentation opaque, which is why I often try to help fix it.
Of course, perhaps I’m a moron. People have called me that many times, and they are probably right a lot of the time. I’m not as young as I once was, my memory has become poor, I often miss obvious things, and I’m clearly not in the league of many people I know. Regardless, though, I’m more representative of what working OCaml programmers will be like if the language gets a lot more users than the best of the best programmers in the world are. (Perhaps you might see that as a reason to prevent entry of more people into the ecosystem?)
Documentation is not usually viewed as a contest to see how compact you can make a description that is still technically accurate, or as an adversarial game in which one attempts to avoid giving too much away. It is a way to assist people who are trying to get their work done. If you are cruel to the users of your system, if you spend your time trying to remove all redundancy and ignore the interests of the people trying to read the documents, if you make it too hard for someone who is reading to figure out what something does, they will respond in kind by walking away. Now, perhaps you want them to walk away, maybe you feel your library would be contaminated by having too many people like me using it, but you should be aware that is a potential consequence.
I’ve given examples from other programming languages in previous threads on documentation. I’ll pick another domain today. I’m a long time user of Unix — 35 years or so — and one of the nice things about most Unix variants is that the man pages for every single system call and library call describe those calls in substantial detail. They explain the motivation for the call, they explain what happens when the parameters are edge cases, they give hints and examples.
Even the most compact such man page, with only a few sentences, tries hard to cover all the bases and explain both motivation and use. See, for example, the following man pages from NetBSD:
The NetBSD memcpy documentation
The NetBSD read system call documentation
The NetBSD uvm kernel subsystem documentation
Note that the one there, for UVM, is the documentation of an internal kernel interface. Those get manual pages too. The creators of NetBSD take care to carefully and fully explain all such interfaces, even though only very skilled programmers typically work on the kernel. This makes life easier for everyone — new kernel programmers don’t need to constantly ask old timers (who may not even be around any more) how things work, old timers have good reference material to work from, and people even avoid problems like forgetting what invariants are supposed to be maintained and the like because they’re documented instead of being part of an unwritten lore.
Note this is in documentation that is intended for working users of the system, and was written by quite expert people for use by others. It is not introductory material. In spite of having worked with many great kernel programmers and systems programmers, I’ve never seen a single one complain that the documentation was too verbose, even though it is substantially longer than the documentation some people believe is sufficient, say when documenting OCaml libraries.
BTW, I’ve been using menhir a lot in recent months, and in spite of the fact that it has a long and very complete manual, I have never thought to myself “if only this manual was shorter! It’s too hard to find things!” — instead, I’ve been glad every time I’ve been puzzled that the manual almost always explains things if I re-check it. Perhaps you are upset that the manual is too complete, of course.
Your comment speaks for itself.
