Comment by makeitdouble | Hacker News Reader

Comment by makeitdouble | Hacker News Reader

> The purpose of technical documentation is to take someone who has never seen your project, teach them to be an expert user of it, and support them once they become an expert.

I would like to understand how this would fly for any other domain.

For instance if I buy skillet pan at a home center I generally get 3 lines of advice on how to clean it, and am supposed to then spend perhaps 6 months of trial and error and go through dozens hours or youtube and litterature to become an decent user.

If I buy a car there will be a 400 page user manual, yet no indication on how to replace the rear axle, or how to realign the wheels, or anything that would qualify me as an expert.

If I buy a violin there will be absolutely no instruction whatsoever and I might spend a lifetime to become an expert at it.

Documentation in the real world is usually third party, targeted at a very specific need of a specific public, and isn't supposed to single-handedly make you an expert at anything. I think this gets lost a lot in how people try to document their work and what they expect from projects maintained by volunteers for instance.

PS: by that token, what I expect from documentation is to be absolutely true and accurate. If it's a tall order, no documentation is fine as long as I can spend my time discovering on my own.

A high minded extremely precise but completely obsolete tutorial is IMHO worse than no tutorial in the first place in that a potentially infinite amount of user time will be lost from it, in balance of the few hours the first users gained from it when it was still relevant.

My domain is mechanical engineering. In my discipline, the Parker O-Ring catalog or the Omega Sensors catalog are basically textbooks which teach you how to specify and select seals and sensors. They create experts, and in the process, create sales and users.

The really outstanding trick of these catalogs is they also work as shortcuts. You can go to a table and pick an O-ring with very little expertise, and it will tell you the groove size, corner radius, etc.

In short, when you're documenting tools or engineering components, and your audience is tool users, teaching is a highly effective approach.

My first job out of college was mostly designing hardware and writing product user manuals for our industrial I/O interfaces. I agree: those massive Omega catalogs were like textbooks to me. I learned an enormous amount about sensors and how to interface to them and that knowledge is still useful decades later.

One thing missing in this discussion is that the audience is important. Omega Sensor catalogs are great for design engineers. OTOH, you can find a lot of the same products in a McMaster-Carr catalog, but their focus is on the buyer and they are well optimized to sell to that person.

Hm. I'm trying to see how these examples here match what the article focus is.

The article focus is the shape and structure of useful documentation, provided by the project or by third parties, that, the article doesn't say.

Now. Skillets are a commodity. Training material is completely detached from the product, except maybe for cleaning and maintenance. For motor vehicles, driving instruction is detached from the product. The vehicle manual focuses on how to use _this_ car (in contrast to how to use _a_ car, e.g. in traffic). And violin expertise needs a personal trainer.

And likewise, for some programming languages, for example a C compiler, the user manual just teaches how to configure _this_ compiler. It won't teach you C. You buy separate books for C.

But for a new language? a new paradigm?

Let's look at an apples to apples comparison, what would be real-world products of comparable complexity? Advanced Games could be an example. Physical Games that is, like Settlers of Catan.

And of course these come with documentation, because of course they'll desperately fail if the documentation isn't helpful.

We could argue if the presentation of how to get to useful documentation fits today's attention span, I think both the article and the linked resources are very chatty, but the contents is worth reading if you want your technical software product to be successful, imnsho.

The article felt off to me, and trying to pinpoint why led me back to the core premise of it.

On the examples given, we're talking about building tools. The point of a new library is to integrate into projects, understand its model, adjust and maintain it (deal with the requirements, dependencies, upgrade cycle etc), so to me getting taught how to use it is only a small part of the story, and could be potentially irrelevant.

I've used brand new libraries that have absolutely no documentation and it was fine for me and the team.

What the article really focuses on is perhaps more akin to quick onboarding and marketing.

> what would be real-world products of comparable complexity?

A new car will be the same level of complexity. You see it as different if you focus on the simplest part of it (going from A to B), but even for driving a new car will effectively have a learning curve, he tires don't grip the same, the engine requires a different driving style, the length and volume might require adjustement as well. And that's only the tip of the iceberg, as you'll need to understand how it's wired, how the panels are assembled and what standards are used for the parts to maintain or adjust it to your needs. You'll need to dig deeper if you're planning on running it on tracks or races.

Settlers of Catan comes with a booklet because the rules are the game, and the whole point is to bind the players to the rules. That's generally not the case for building tools (except for DRM or license management?), surely not for a new language.

Reply on news.ycombinator.com