My pet hate: heredoc
My pet hate is "heredoc", whenever I see "it's better than nothing" I just plead back at the screen "NO IT ****** ISN’T".
Were there no such thing, someone might at least try, and "partial" good beats "complete" drivel every time for me.
Of course I would have no problem with useful information such as routine signatures being automatically extracted from the source code, but a) forcing the programmer to replicate that information as a comment is liable to error and just plain stupid, and b) describing the collected remarks as documentation is plain incorrect, a far better term would be utter garbage.
For a completely random example of what vexes me, try this link, and I mean who exactly does that actually help, ever?
There are without doubt many sound reasons for breaking something like GTK down into five or more implementation units, but prohibiting any cross-references and limiting the search function to one fifth or less of the product is nothing short of utterly ridiculous. I have in fact resorted to running Dependency Walker to get and save a list of the available functions, and it is quite something that running that a dozen or more times is way easier than navigating the official (di-docgen) help documents! The GTK docs quite adamantly state they know nothing about the window decorations, to the extent that questions of that ilk go unanswered on StackOverflow, but actually GDK does know! Why on earth though, would the GDK team ever want to proof read the GTK docs??!! Were the GTK docs a car manual, they’d have some information about every component, but essentially nothing more than what you could ascertain by picking up and inspecting part JG37-004T yourself, and only a few rare accidental hints where it might go or what it actually does or how to put anything at all together. Apart from the function signatures, which I find easier to obtain by searching the GTK sources anyway, for me the GTK docs are almost completely useless. Just recently I was staring at a "fill" parameter, and in about seven different places it said something like "The fill parameter contains the fill setting for the control". I still have absolutely no idea what it was - a bool, an enum, a width, a colour, behavioural, expansion... Other heredocs are equally awful.
The GTK3 docs severely vex me simply by containing the phrase "No further description available" literally tens of thousands of times.
The GTK4 docs are not magically better just because someone (presumably) tweaked di-docgen to stop outputting that particular phrase.
If you can tell me (reasonably precisely, and I’ll ignore "delete rants") what warrants improvement in these docs, please do!
Programmers are not generally noted for their eloquence in explaining things in simple terms, and (evidently) only very rarely give any consideration to the holositic whole. They say a picture paints a thousand words, but I’d wager it would very rarely even cross the mind of a programmer to insert an image link in the middle of a heredoc comment, and even if it did, they probably wouldn’t know how to write an xxgen-compatible link, if such a thing even exists, or for that matter where precisely the image should be stored. It still shocks me there are no screenshots at all in either the official GTK or WinAPI docs. Seriously, how can you possibly claim to have adequately documented a graphical user interface without any pictures whatsoever?
So, why have so many technical authors been sacked and this mess been foisted upon us? Once object orientation is allowed to actively encourage complexity, technical authors could simply never keep up, and quite probably the world wanted a way to slow those crazy programmers down, at least and most cruciually on the meaningless abstraction side of things, but, alas, it didn’t really work. At least some of my issues with heredoc no doubt lie with the astonishing appetite throughout the software industry as a whole to create things so ridiculously over-complicated they could simply never be properly documented. Then again, heredoc enables them to pretend they have, whereas if they had to produce proper docs, they would probably also produce software which would be far easier to use.
Were there no such thing, someone might at least try, and "partial" good beats "complete" drivel every time for me.
Of course I would have no problem with useful information such as routine signatures being automatically extracted from the source code, but a) forcing the programmer to replicate that information as a comment is liable to error and just plain stupid, and b) describing the collected remarks as documentation is plain incorrect, a far better term would be utter garbage.
For a completely random example of what vexes me, try this link, and I mean who exactly does that actually help, ever?
There are without doubt many sound reasons for breaking something like GTK down into five or more implementation units, but prohibiting any cross-references and limiting the search function to one fifth or less of the product is nothing short of utterly ridiculous. I have in fact resorted to running Dependency Walker to get and save a list of the available functions, and it is quite something that running that a dozen or more times is way easier than navigating the official (di-docgen) help documents! The GTK docs quite adamantly state they know nothing about the window decorations, to the extent that questions of that ilk go unanswered on StackOverflow, but actually GDK does know! Why on earth though, would the GDK team ever want to proof read the GTK docs??!! Were the GTK docs a car manual, they’d have some information about every component, but essentially nothing more than what you could ascertain by picking up and inspecting part JG37-004T yourself, and only a few rare accidental hints where it might go or what it actually does or how to put anything at all together. Apart from the function signatures, which I find easier to obtain by searching the GTK sources anyway, for me the GTK docs are almost completely useless. Just recently I was staring at a "fill" parameter, and in about seven different places it said something like "The fill parameter contains the fill setting for the control". I still have absolutely no idea what it was - a bool, an enum, a width, a colour, behavioural, expansion... Other heredocs are equally awful.
The GTK3 docs severely vex me simply by containing the phrase "No further description available" literally tens of thousands of times.
The GTK4 docs are not magically better just because someone (presumably) tweaked di-docgen to stop outputting that particular phrase.
If you can tell me (reasonably precisely, and I’ll ignore "delete rants") what warrants improvement in these docs, please do!
Programmers are not generally noted for their eloquence in explaining things in simple terms, and (evidently) only very rarely give any consideration to the holositic whole. They say a picture paints a thousand words, but I’d wager it would very rarely even cross the mind of a programmer to insert an image link in the middle of a heredoc comment, and even if it did, they probably wouldn’t know how to write an xxgen-compatible link, if such a thing even exists, or for that matter where precisely the image should be stored. It still shocks me there are no screenshots at all in either the official GTK or WinAPI docs. Seriously, how can you possibly claim to have adequately documented a graphical user interface without any pictures whatsoever?
So, why have so many technical authors been sacked and this mess been foisted upon us? Once object orientation is allowed to actively encourage complexity, technical authors could simply never keep up, and quite probably the world wanted a way to slow those crazy programmers down, at least and most cruciually on the meaningless abstraction side of things, but, alas, it didn’t really work. At least some of my issues with heredoc no doubt lie with the astonishing appetite throughout the software industry as a whole to create things so ridiculously over-complicated they could simply never be properly documented. Then again, heredoc enables them to pretend they have, whereas if they had to produce proper docs, they would probably also produce software which would be far easier to use.