61–70 of 87 posts
Isn't this more likely an example of LLM-crappification? As in, the reason it isn't documented is that no one has a clue...
In that case, it should be documented at least that the process is driven by LLM and hence, it's not known exactly how it makes a decision...but I guess that would not look good to most users so they just leave it out.
Welcome to the stupid singularity.
I've called this ritual-taboo programming for decades. It happens for user interfaces and APIs when the documentation is absent, or only consists of examples. If there's no reference documentation, everything is a copy of something someone else did. Nobody understands how it really works. Now, for some interfaces, this isn't too bad. Most people don't know why US AC power plugs are polarized, or what the ground prong…
I agree to some extent, but I'd say it depends on the programming language. For instance, in Python, you absolutely need documentation because you don't know what type is expected, what different values can be passed or even the optional kwargs etc. It's also very common to pass strings as parameters when one should be using enums, which means you can't know what are the possible values without having the doc or divi…
Something like Hoogle becomes a necessity if you want your type system to replace the need for documentation.
Earlier quoted context omitted.
In other words, it's a principal-agent problem. The ICs (agents) tasked with creating documentation see it as extra work with no immediate payoff for them, and indeed even some long term downsides; the org (principal) bears the hidden costs of its absence - inefficiency, delays, trouble when Mr Magic Touch switches jobs. There's nothing special in kind about this, it happens in all industries. The fix? Stop leaving i…
Forced documentation by ICs could be poorly written, leave things out or quickly sync out of date. I think there should be a dedicated team tasked with managing this documentation.
Earlier quoted context omitted.
How do you view self-documenting interfaces? Have you ever read the manual for your browser which you are using to make this comment? The OS on which the browser is running? The device on which they are running? I think there are interfaces that need to be usable assuming documentation will not be read. These are of course user interfaces, not necessarily APIs. But if you are creating something like a library of basi…
> How do you view self-documenting interfaces? > Have you ever read the manual for your browser which you are using to make this comment? The OS on which the browser is running? The device on which they are running? Have you ever read the manual for the tools used to build the building that you live in? A manual for the trowels, tape, mud, and drywall that built and makes up your walls? Or a manual for the Romex in t…
I am laughing at ‘remaining frontiers’ of UX design. This year for Christmas I wish for mobile devices with browsers that don’t crash and lose my form entry. This year, I wish for YouTube that doesn’t find new ways to turn on autoplay (TV queue being the latest one I had to turn off, despite having already turned off AutoPlay on that device in settings… each of my devices has autoplay turned off… yet TV queue came with autoplay turned on… crooked YouTube!) But sadly, this kind of thing is not what the state AGs are looking at—-but to me, the constant bypassing of disabled AutoPlay is anti-consumer AF and must be stopped. That is the remaining frontier.
I've called this ritual-taboo programming for decades. It happens for user interfaces and APIs when the documentation is absent, or only consists of examples. If there's no reference documentation, everything is a copy of something someone else did. Nobody understands how it really works. Now, for some interfaces, this isn't too bad. Most people don't know why US AC power plugs are polarized, or what the ground prong…
They key point to me in TFA: "The feature is a black box"
This doesn't apply to software internal documentation. It's not a black box and you can give any deep you want to know what is and isn't implemented, what has explicit tests and who wrote it.
Whether comments on those are a waste of time of not will come down to how long it will take to write useful comments, how long it will take for the reader to understand the class/function/method otherwise, how much maintenance will happen on the comment itself after it's written, what it will cost when it will "rot", and what else (e.g. tests ?) the dev could do with all that time.
Earlier quoted context omitted.
Both is important. And related. Documentation needs to be discoverable. I was amazed when I tried jj (jujutsu, the "new git") and it popped me into some kind of weird textual user interface after executing `jj split` and I felt lost. I guessed, pressing `?` won't hurt and it told me just to use the mouse. The menues showed the related hot keys. But the actual documentation of the tool has room for improvement. I need…
our architects love building the house before making the drawings. i imagine we will probably figure it out eventually when the feature set can be strictly defined. (maybe you eventually want a bath tub and a toilet in each room? maybe not?)
This is different than commercial work where in addition to the original plans, you also get as-builts, which can be expected to be accurate, and are expected to be updated.
If you only want to document once, it makes sense to do it once the thing is built, rather than before, because there's a good chance the actual thing will be different than the plan. If you will update it, it might make sense to start documentation before the thing is built.
Of course, if you never get around to writing documentation, it never needs to be updated.
Earlier quoted context omitted.
> But if you are creating something like a library of basic math functions I would rather read your code than your docs. Talking about software specifically: this is the exact wrong way to do it. A programming interface should be easy to use and "self-documented" to some extent (by, e.g. using the type system as much as possible to make bad states unrepresentable), but only very simple interfaces are usable that way.…
Yeah thats a horrible approach that creates massive additional costs down the line, usually not author's problem anymore though. Can't really put finger on it precisely, maybe its too large ego (my time is too valuable for some pesky documentation for idiots, I am a superstar! No you're not, you are at vee best a brilliant junior...). Or maybe lack of basic empathy, surprisingly high number of humans can over time le…
Usually a long comment is a smell. If the way something works isn't obvious and must be explained, it can probably be better designed.
Code changes and then comments have to be updated, and often aren't. If they aren't just wrong, the context is often so changed that they aren't useful. You wind up reading the legacy code anyway, and you and the author both wasted time with comments.
My team is smart and competent. I need them to read the code to make sure their changes are safe, anyway. They do not need their hands held. They don't need me to waste time writing comments that will soon be outdated, or that explain something I should have designed better.
Finally, management doesn't apply an OKR to intangible code metrics like internal documentation. Should they? I don't know, but it's their code, not mine, so I'll write it to the standard they apply.
These are the reasons you have to work in code that is poorly documented. It has nothing to do with a lack of empathy -- if I were to allow my employer to extract extra value from me by using my empathy for my teammates as a lever that would be exploitation. If I spend more time on documentation -- which the employer doesn't value -- instead of functionality, I'll be punished at review time for wasting time on worthless things.
Maybe you should stop letting your company manipulate you into doing more work than they're paying for. If they value internal documentation, they'll create an OKR or KPI or whatever to make sure you're paid to do it. Otherwise it's unpaid labor for a for profit corporation. I'm not doing that. Are you?
Earlier quoted context omitted.
I tend to use in-code documentation[0]. Works pretty well. Could still [theoretically] go out of date, but that hasn't happened, so far. The one thing that does happen, though, is copy/pasta errors. I'll copy a bunch of code, including the headerdocs, and paste, but forget to adjust the docs. [0] https://littlegreenviper.com/leaving-a-legacy/
But it covers only how to use a function if you know what the system is meant to do or know which function to call in the first place. You need some overalls documentation to explain the concepts and how to put things together. When the user understands that you can use in-code documentation but even then only if you need to use one function at a time - there needs an explanation of how to put things together.
Seems to me documentation can also be superstition if it's out of date. I wonder if LLMs can generate docs at any reasonable level of usefulness and accuracy Speaking of which, I just tried using ChatGPT to create a React app with typescript and rollup. What it generated didn't work (got errors). Of course I could tell it the errors and it fixed them but it suggests they aren't yet ready to write accurate docs
Why would you bring ML up? The entire example problem brought up by TFA is because the ink-to-shape transform likely uses some ML behind the scenes (plain interpolation likely) , and as consequence, it is an _indocumentable_ blackbox even if you wanted to document it. Superstition is the only way you can make it work. In fact, "superstition" very neatly defines most prompt engineering for LLMs.
Its weirdly fascinating how this is developing. Like some people boldly claiming that if you offer to tip your LLM it does better. And if you say things like "Think hard and check your work" it gives more accurate results.