Trolltech's Documentation Process

https://rant.gulbrandsen.priv.no/udoc/trolltech-documentation-process

by whatever3 • 2 years ago

56 16 2 years ago

rant.gulbrandsen.priv.no

solarkraft• 2 years ago

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.

LorenDB• 2 years ago

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.

IshKebab• 2 years ago

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.

oldsecondhand• 2 years ago

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

GuB-422• 2 years ago

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.

haolez• 2 years ago

Racket's documentation is absurdly good.

hoseja• 2 years ago

If this is the best... I weep.

ghosty141• 2 years ago

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.

jclay• 2 years ago

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.

firesteelrain• 2 years ago

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.

ChrisMarshallNY• 2 years ago

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.

PaulDavisThe1st• 2 years ago

Title should say 2012.

starkparker• 2 years ago

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.

Trolltech's Documentation Process

Related Stories