Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The Opposite of Documentation is Superstition (2020)

buttondown.com

Post reply on HN
Print view View original

51–60 of 87 posts

Re: The Opposite of Documentation is Superstition (2020)

#51

Post by pasc1878 »

ChrisMarshallNY wrote: post #11
nox101 wrote: post #4

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

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.

Re: The Opposite of Documentation is Superstition (2020)

#52

Post by ChrisMarshallNY »

pasc1878 wrote: post #51
ChrisMarshallNY wrote: post #11

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.

That's what I use the README for.

With Apple's docc, you can drop READMEs throughout the system, and they show up in Xcode's doc browser (and can be referenced from the code).

Re: The Opposite of Documentation is Superstition (2020)

#53

Post by hiAndrewQuinn »

tempodox wrote: post #48
Animats wrote: post #15

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…

It's always the same problem: The work generated by doing documentation, including the possible need for specialized talent, is quite directly perceivable. The work generated by the absence of documentation is more under the radar and disguised as “cost of doing business”, which makes it harder to convince the anti-documentation crowd. Not to mention the “job security” aspect of everything being in the heads of the I…

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 it optional. Tie documentation to performance reviews, bake it into deliverables, reward teams for knowledge-sharing. If you can’t convince them with logic, align incentives so ICs can’t ignore it. It's either that, or accept that you believe ICs have better things to do with their time. But make a conscious choice either way, I'm begging you!

Re: The Opposite of Documentation is Superstition (2020)

#54

Post by jajko »

brabel wrote: post #44
IgorPartola wrote: post #20

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…

> 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 learn how to work in society but any novel situation requiring some empathy they handle like mammoth ina porcelaine shop.

Or something else in similar vein. That was quite shocking, entering adulthood and discovering vast number of folks have such issues

Re: The Opposite of Documentation is Superstition (2020)

#55

Post by ValentinA23 »

martin-t wrote: post #49
nox101 wrote: post #4

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

I inherited 100k LoC "documented" by an LLM. LLMs can put into words what a programmer can infer from struct definitions, function signatures, names and even taking a cursory look at a function body. LLMs cannot retroactively find out the _why_ of design choices. If you don't document the reasons behind decisions while making them, they'll be lost, which is exactly what leads to superstition. As a result, changing co…

Related: Show HN: Auto Wiki – Turn your codebase into a Wiki

https://news.ycombinator.com/item?id=38915999

Re: The Opposite of Documentation is Superstition (2020)

#57

Post by sakex »

Animats wrote: post #15

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 diving into the code.

In Rust however you can get away with way less documentation because the type system and signatures are self explanatory. And if you're doing things right, the set of values you can pass to your function is limited.

Re: The Opposite of Documentation is Superstition (2020)

#58

Post by m348e912 »

drewcoo wrote: post #40
m348e912 wrote: post #3

Earlier quoted context omitted.

There could be a business to be made in capturing and disseminating tribal knowledge for organizations. Even orgs with the best documentation don't have a great mechanism to capture and make available tribal knowledge which is un-authoritative, sometimes conflicting, and constantly changing. In the past I made an effort to address this by creating a unofficial but quickly searchable document repository documenting ev…

If the businesses valued it, it would be documented knowledge. It's clearly not worth the time or money to document. If the workers values it, it would likely be documented knowledge. Undocumented knowledge can be job security.

> If the workers values it, it would likely be documented knowledge. Undocumented knowledge can be job security.

You're mostly right. It's paradoxical in some ways. Workers generally won't go through the trouble of documenting tribal knowledge. However they greatly appreciate if someone else does.

Re: The Opposite of Documentation is Superstition (2020)

#59

Post by onemoresoop »

hiAndrewQuinn wrote: post #53
tempodox wrote: post #48

Earlier quoted context omitted.

It's always the same problem: The work generated by doing documentation, including the possible need for specialized talent, is quite directly perceivable. The work generated by the absence of documentation is more under the radar and disguised as “cost of doing business”, which makes it harder to convince the anti-documentation crowd. Not to mention the “job security” aspect of everything being in the heads of the I…

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.

Re: The Opposite of Documentation is Superstition (2020)

#60

Post by onemoresoop »

nox101 wrote: post #4

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

> I wonder if LLMs can generate docs at any reasonable level of usefulness and accurate

A lot of times documentation isn’t read by anyone for stretches of time till it’s needed. I imagine documentation by LLMs will make the situation worse if nobody verifies its corectness. I don’t believe in magic solution, good documentation that is not out of date requires work and if a company doesn’t allocate resources no magic will fill in the gaps.

Post reply on HN