[RajT88]

I have found that even the group I'm in being documentation-heavy, it's hard to read through everything and build the same context that another engineer has all stuffed into their head.

As you mention:

> available and searchable digitally.

Even with 100% everything written down, it takes a while to build up that context, and even carefully written documentation can have subtleties which send a consumer the wrong way.

Things are a lot easier than they used to be, but still not easy-easy.

[cduzz]

Documentation is extraordinarily difficult to create. You need to anticipate the potential questions and answer them and anticipate all the potential perspectives and answer them from that perspective.

What is enough? A reference describing all of a thing? The source code to a thing? The source code and build chain to make the thing? The source code, build chain, source code to the build chain to build the build chain to build the thing? The source code and the machine and the tape drive to read the tapes to build the ....

How much documentation for TOPS-10 would you need to implement wireguard on a toad? How much context do you need to even make that sentence even make any sense at all?

[RajT88]

Yep, and the example I like to go back to is API docs, or command line docs.

One I was reading this week had a field for "language", but doesn't clue you in to the valid values by providing a working example. English for example could be:

English

English (US)

en

en-US

eng

1033

409

...And that's just for the US dialect of English. And also doesn't tell you if any of this is case-sensitive or not! Sometimes yes, sometimes no.