> Our documentation process worked (we wrote documentation and it largely satisfied the readers)

IIRC this is quite an understatement; Qt documentation is regarded as some of the best in GUI toolkits.

I mainly work with Qt, so I don't have a ton of experience with other projects' documentation, but I have to wonder if Qt's documentation is some of the best in all of programming.

It certainly has many contenders (cppreference has exhaustive documentation of all things C++), but it's very, very good.

IMHO Java's official documentation is quite decent as well.

Qt documentation is excellent, and so is cppreference. Definitely among the best. I also like many of the of the UNIX manpages, though it is uneven.

I still often find myself reaching for the source code of Qt, which is also of great quality. Some details may be unclear, but mistakes are rare. I don't remember seeing documentation and code contradicting each others

This, by the way, is one reason why I think open source is so important. There is no more accurate documentation than the source code.

> There is no more accurate documentation than the source code.

"Accurate" needs unpicking. As the unambiguous representation of what the computer should do, yes. It is the sole source of truth. As the representation of what the author thought the computer should do, or does in fact do, it is wanting.

This is why I dislike the StackOverflow style of snark where people tell others to just read the code, as a substitute for documentation.

Documentation should record authorial intent, and also observations where intent might sometimes not be satisfied. The reader should be able to inspect code to determine for themselves whether it implements the intent or does not (in which case, a bug may be claimed).

For example, if I write in the docs that foo(int bar) returns double the value of bar, that is intent. You the reader might inspect the code and see that there are cases where it does not. The author might also inform you that they know of cases where care must be exercised (eg bar is very large).

OpenBSD manpages are examples of doing it right, by and large. They tell you what is supposed to happen, limits and issues that they know about, and you can get the source if you want to inspect things yourself.

The code is not a substitute for good documentation, which is definitely the case for Qt.

But unfortunately, it is not always the case. From hobby projects to internal company software, you'd be lucky to have documentation at all, and when you have, it is often outdated or just wrong. Popular, company-backed projects are usually good, as it is the case for Qt. Because companies have a budget for it, you need a budget, because good documentation is expensive, and generally not something people do "for fun".

Prestige projects (GNU, BSD, etc...) may get good documentation "for free" as people who are not developers can get credits, but it is not a given. For example, Linux kernel internal APIs are poorly documented, that they are (deliberately) unstable probably doesn't help. The code is great though.

At work, the first think I ask for when starting to work on a project is the source code, because documentation is almost always terrible (if it exists). And in the rare case where it isn't, that's when there is at least one person who is paid full time to do just that.

When I worked on Qt, I introduced differences between code and documentation on purpose. I deleted documentation about things that worked in principle but led to user trouble and support questions, I deleted things that we intended to change in a future version.

https://rant.gulbrandsen.priv.no/udoc/use-the-source-luke

Which is more accurate, the documentation that describe the current and future source code, or that which describes the current source perfectly?

Racket's documentation is absurdly good.

If this is the best... I weep.

Yeah it's really among the best. Microsoft's C++ documentation in the Visual Studio 6.0 days was also amazing, before they completely ruined it by pushing it all to the web and mixing it up with irrelevant stuff.

Looking through the list of things on devdocs.io the only other thing I can think of that is as good is MDN.

Qts doc is good but REALLY lacks in the details. For example how things composit with each other is generally undocumented and the fact that their codebase is quite old and full of techdebt makes that part very annoying for advanced use.

An example: how in QML the Repeater element works inside an ObjectModel.

I agree. Topics like “how is the lifetime of a QObject exposed to the QML engine managed?” lack coverage and clarity. On the surface it is simple, but in practice it’s an extremely complex topic that has been a source for many bugs in our medium to large QML desktop app.

We contribute upstream a bit and we had documentation updates to clarify the stability of pointers to QHash elements rejected. ¯\_(ツ)_/¯

Personally, we superbuild bleeding edge Qt with the source code in tree so that it’s trivial to go to definition and inspect behavior. Makes the experience substantially better.

I first used Qt back in 2002-2003 timeframe IIRC. Its documentation was excellent for a burgeoning computer science student. We used Qt in my classes.

Title should say 2012.

I really enjoyed his blog!

On-topic: Documentation is good, and I'm glad someone like him was able to get it going.

We used Qt for internal tools, in my Day Job, but never shipped anything on it.

> More documentation was gradually written by technical writers, less by programmers. That led to some better explanations, some longer explanations, to lots of words, and here and there to meaningless drivel. ... "SetFoo sets the foo" without mentioning either the nature or details of foo. Written by someone who didn't understand what foo is or what matters about foo.

This is a process problem more than anything. If the technical writers don't understand the problem or solution then people either aren't communicating, the writers don't have sufficient access, or the writers aren't qualified.