|
Top-level
 "apropos multichar" comes up empty too, assuming I know about it. Tell me what I should have done differently. This is a _typo in 'hello world'_. What trail of breadcrumbs should I have followed that would have gotten me from "incompatible integer to pointer conversion passing 'int' to parameter of type 'const char *'" to "You want double-quotes, not single quotes there", using the error messages and docs? You complain about "StacktGPT Developers?" Well, this is what people are up against. 22 comments
@mhoye in this particular case the trail of breadcrumbs would have been basic language knowledge.
0
0
1 Nov 2023 at 16:33 | Open on social.immibis.com
@mhoye I think this is an excellent walkthrough of an all-too-common situation. Thanks for taking the time to make it. @mhoye The number of responses in the thread treating this as purely a documentation problem is also really alarming, tbh. There are human factors issues at multiple stages of this! The earliest one is probably the design of C, where the difference between values occupying types with wildly different semantics is expressed via the shift key alone, for example. @mhoye Docs and error messages retrench that design problem without meaningfully remediating it, and that gets us to docs as one of the multitude of cultural failure points in this chain.  @mhoye This 100%!! My god I can't believe how many times I've looked with despair at convoluted docs when a series of explained, code examples would have gone 1000x better. That's why people love StackOverflow, because the answers usually include *example code*. It's the programming equivalent of 'a picture is worth a thousand words'. Show me don't tell me.  I often suspect if the ultimate “zen” of documentation is just a well structured and indexed series of code examples with outputs and inputs. Similarly for research papers except with figures and plots. @syntaxseed @mhoye @gvwilson after a few decades watching and doing software development and maintenance I have these recurring thoughts: - I wish I had been taught the basics of technical writing at university. @graydon yeah. We’ll get to the point where this is understood as a load-bearing archaeology exercise, I think, that yes there’s lead in the pipes and asbestos in the walls and you don’t even wanna know how big those roaches are, but _some_ of these pipes still bring people drinkable water and heating, and here are the skills and tools you need to work safely in this environment, but we’re not building anything new like this ever, whatever those weird PDP-11 Reenactment Society people say.  @mhoye What's interesting is that all of those would've worked in #Elisp without ever leaving #Emacs. Much of it with #CommonLisp and #SLIME too. Most of the implementations also come with #info #manuals and their source-code (for those things not mentioned in the manual), and hyperspec.el also handles searching through the #HyperSpec locally on one's machine (it's packaged on Debian) and provides keybinds to search symbols automatically right from your editor. C lacks most of this. @mhoye #Interlisp did it better than most modern #CommonLisp environments though, if what I recall hearing is correct, as the documentation didn't require additional setup (pointing the editor at the docs' location).  @mhoye@mastodon.social this is one of the reasons i generally stray away from things written in C(++) and why to some "not written in C" is seen as a selling point  Almost all projects/products have two mutually exclusive problems at the same time; "Too Much Information" and "Too Little Information", depending on WHO you ask and WHEN you ask. I think the "real" problem is much more about psychology and personal character. Why would software require less "practice" to reach "proficiency" than for instance becoming a doctor, a lawyer, a musician,...? I would argue that no matter what docs you have, it can't replace experience/practice. But maybe I am missing your whole point... If this was only about C/C++ not understanding what are warnings and what are errors, then perhaps you should chose to work with a different language. Most of the weird errors in C are due to legacy code, and you could (I do) set compiler switches to treat all warnings to errors. Every single one of us has probably made a joke about searching recipe blogs for basic information, and finding "Here's how you make boiled eggs. It's easy and fun! I was in an alley in the outskirts of Algiers in 1987 the first time I watched a man die. I can still remember the blistering sun, the smell. Since then" for like forty pages of meaningful story and protein chemistry, all while you are in front of a pot of boiling water with an egg and your question is "how long do I boil an egg". That is most of the tech documentation experience. Precisely like that, but with the detailed spec and the interface details instead of the dead man in an Algerian alleyway and the protein chemistry. I understand that might seem like a big difference but the experience is the same.  @mhoye and in the end, it turns out the story actually took place in Tangier... |
Gregory's Server