It's not a one-way transfer of information.

- The student has questions that it wouldn't have occurred to the teacher to answer.

- The student gets confused and asks for things to be rephrased or reframed.

- The student has questions that don't currently have static answers, but get computed by the teacher in real time, according to an intuition and assimilation of the facts that the student is only beginning to develop.

- The teacher's answers are up to date, whether or not he has actually exercised the diligence to maintain the textbook.

- The teacher fields the questions that the specific students ramping on the project actually have, rather than trying to anticipate all possible questions of all hypothetical students (and still failing).

There is a reason we have college and not just reading lists. And those are subjects where the economics support massive investments in discovering the best / most broadly useful ways to present the ideas. The average software project isn't that.

The commoditized software factory is an MBA fantasy. The expertise held by "key persons" is a software team's greatest asset.

I learned f all in college and everything through reading and watching back video tutorials/lectures. YMMV.

Then you had poor teachers or a poor structure that didn't give you access to teachers in the right way.

While documentation has both advantages and disadvantages compared to in-person training, video tutorials are strictly worse than an interactive lecture.

I’m an autodidact. No teacher can provide the density and velocity of information and knowledge the Internet, science papers and books can provide. I can’t watch a lecture at 2x speed if its live. I can’t cherry pick. I have to be at a certain place at a certain time when I might not be in the right headspace. Then add on top that’s it’s basically a crapshoot whether or not you get along with your teacher or not. I don’t regret going to college but I didn’t gain much academic knowledge there either.

100%. As an undergrad in the 90s I came to this conclusion as well. Then when YouTube, Khan Academy, and MOOCs hit critical mass in the 2010s, I could see the beginning of the end. COVID-19 has greatly accelerated the demise of in-person learning, and the fact that colleges continue to charge the same tuition is clear evidence that what they're selling isn't education, it's credentialling.

> I can’t watch a lecture at 2x speed if its live. I can’t cherry pick.

If you have a 1:1 teacher you can just tell them what you already know and they can jump to the parts you don't. Much more efficient than skipping through a video for interesting snippets.

I think 1:1 or even one to many teaching is amazing but more for the cutting edge stuff. It’s changing how you think more than what you know.

Reading and writing scale in theory. They require an organization staffed with people who are strong readers and writers. Unfortunately, many people, especially those forced into remote work during the pandemic, are not. They will not read through explicit, clear, but long documentation; they will not respond by writing questions of their own, and will often fail at writing explicit and clear documentation of their own.

You are who you hire.

....They won't do their job.

Their job is not to write docs, it's to produce a product. The docs are a possible tool towards that goal, but there are others, with different trade-offs - such as in-person trainings.

It is fairly obvious that most of the industry believes the opposite from you here - thorough docs are an extremely expensive way of achieving good context, and as such are usually replaced with training sessions, which seem to fit most people better up to some point.

You can’t do in-person training properly without docs. It’s not an either or choice.

I think it should help in a way. But I also believe that people overestimate how well one can learn in depth about a complex problem from reading or any mainly passive activity alone.

I know there is this theory about learning styles but it's largely debunked.

To get a really solid understanding of a topic such as a business domain and it's interaction with a complex process and application, it takes a certain amount of time and contact with real problems. The only time that people can quickly pick up new ideas from reading is when they have mastered all of the underlying concepts of that knowledge. But applications generally have layers of very specific knowledge required to understand the problem and existing solution.

The point of the article I think is that it's usually going to take a significant amount of time for new developers to become familiar, regardless of how good the source or documentation is.

Unfortunately for me, I started developing really bad RSI around January of last year, and typing has been incredibly painful. In the past I would have discussed things using whiteboards, sitting down side-by-side with code, etc.; these are all very hard to do if typing causes pain.

Interactive sessions are also very helpful, as there are so many assumptions and background material baked into things that often take a long time to unwind. Being able to gauge on-the-fly if the audience understands can save tons of time and confusion.

I've got 17 years of domain experience across 3 companies in the industry; there's no way I'm going to write all that down in my docs.

It sounds like you need a secretary--someone who can type fast and dress up your words for wider distribution in the company.

You're not wrong; I've actually thought about that.

Fortunately my RSI is starting to get better. Therapeutic massage and shoulder rehab exercises have made a big difference (I had a bike accident a few years back, and my shoulders were in pretty bad shape).

I stopped typing on my 2018 MacBook Pro's keyboard (which I think contributed to my problems), and exclusively use an ErgoDox. I've also been taking Magnesium as well as NSAIDs to reduce inflammation. Still a daily struggle, but I can type posts like this one without too much pain.

Dragon works very well for dictation, and a Wacom style tablet works great as a remote substitute for whiteboarding.

There are also voice coding solutions like Talon voice that work well (I use it regularly).

Might be worth trying Dvorak keyboard layout.

Has worked for many, me included.

I think the point that Naur was trying to make is exactly that this process (unfortunately) doesn't scale.

That is my experience at least (even in very well documented projects).

It depends on the situation. Documentation and in-person meetings aren't mutually exclusive. A meeting to go through the docs and update them is often very useful.

Not everything has to be "scalable". There are many parts of the code that only 1 or 3 people will ever work on. In fact in most places I'd say that's most of the code.

I’ve never been unhappy when provided with thorough documentation.

Do you have any examples of sufficiently thorough documentation?

I've basically never been happy with the documentation I've been provided with, whether for internal company code or 3rd party OSS stuff or 3rd party paid stuff...

Just do audits. There are ISO standards for practically everything and you should run internal audits (and external ones if you can afford it for important stuff).