Comment by ThinkBeat | Hacker News Reader

Comment by ThinkBeat | Hacker News Reader

I loved TurboPascal. I agree with everything the post argues.

I would like to expand a bit on it being before the Internet was a huge thing.

The manuals that came with TurboPascal were nearly excellent. It included most of what you would need to get started. When you didn't quite understand something, you had to spend time to figure it out and how to do it well. This could be time consuming, but afterwards you gained important knowledge.

Then there were other books to get, there were "coding" magazines, though at the moment I cant remember any TurboPascal specific ones. and if you were lucky you knew one or two other people who were into coding and you could share problems, solutions, hints and tips. and warez.

There were also a lot of BBSs out there. Where you could ask questions, help others, etc.

These days most people if they face a problem, Google it (maybe now ChatGPT it) find someone posted a solution, cut and paste the crappy code, crosses fingers that it works and off you go.

(or pull down libraries without having any idea what in the world it actually does)

At the same time things have gotten a lot more complex . In my TurboPascal days I knew most of the stack. The programming language, the operating system, assembler, a lot of how the CPU worked.

These days understanding javascript, understanding the runtime / compiler etc, before you even get close to the underlying OS, and certainly not down into assembler amd CPU

I'm not sure whether the issue is stack complexity / depth, but there is definitely something in the culture where it's common for docs and how-tos and Q/A to tell you what to do, the steps/commands/etc, but to do little to help you build any kind of relevant domain model.

This isn't exactly new, there's always been documentation like this, but I think the proportions have changed dramatically since even the early 2000s.

One of my vaguely defined theories is that as valuable as automation is, the culture of automation / process has started to diffuse and act as an influence on how we think, in steps & commands rather than models.

Possible that we've always been steps-results / input-output beings, but I wonder.

I recently created some documentation for a process at work where I explained the 'why' for most of the steps and commands. Not in great detail, but just a bit of detail. I thought that it was good as a step-by-step recipe, while also giving context that could help someone in the event that something didn't go according to plan.

I was asked to remove much of the context that I provided, so as not to confuse the reader, and to make it as direct as possible. This is documentation intended for experienced, technical professionals. I think that the revised documentation is less helpful.

Perhaps it could be restructured to separate out the howto from the explanation to serve the reader’s intended use at the time as described here: https://diataxis.fr

As a tech writer I love the concepts of Diataxis but don't agree with it being invoked here. Context is critical in all four of its quadrants, and its model doesn't apply uniformly to every aspect of every application.

GP did IMO the right thing by understanding the audience first in order to judge what level of context is appropriate. That should be rule 0 before anything in Diataxis gets involved.

I think another factor is the medium through which the docs are to be consumed. If the intended audience are "experienced, technical professionals" as the ggp says, but those folks are arriving at the docs primarily from search engines, then it's likely they are in "how-to mode" [0].

People in "how-to mode" are almost always time-constrained. They need immediate answers so interspersing the why with the how would slow such readers down (since they have to scan more text than they need to [1]). Their impatience will often cause them to bounce from your web page back to the search engine in search of other sources that can provide them with immediate answers.

Without additional context on the medium of delivery of the docs (in-app vs web page vs PDF), it's hard for us commenters to say with certainty whether the decision to remove the "why" was a good call or not.

0: https://diataxis.fr/how-to-guides/

1: https://www.nngroup.com/articles/information-foraging/

I had the same thing. I took the reader through the journey of "why" they should want to work in this way, but apparently that's confusing.

That actually the important part though. If people don't know why they are doing something, they don't do it.

Perhaps you could compromise by moving the “whys” into an appendix to the guide with references from the “how” section.

Yes, too many cookbooks, "with solutions and examples", and no one writes good reference manuals any more.

I kind of get it. I think about a problem, and I am solution focused. Furthermore, I want to learn what I need to implement the solution, and usually don't pay attention to other features that are not directly related to my problem.

However, by giving me a cookbook, the documentators are doing me a disservice in two ways: first, they are greatly limiting the amount of solutions I can use. If my problem is not something they already imagined, I need to find another cookbook or read their source code to find out how to solve it.

And second: they are taking away from me the process of learning about the different parts of the system and how to integrate them into a solution by myself.

And the gotchas are endless. I am using FastAPI and the amount of things I have no idea how they work underneath, until something fails, is mind wrecking.

I wish there was some real reference manual of it, not just the autogenerated function signatures and the most minimally useful documentation I have ever seen. So many things make no sense, and I have to second guess the FastAPI designers all the time.

> there is definitely something in the culture where it's common for docs and how-tos and Q/A to tell you what to do, the steps/commands/etc, but to do little to help you build any kind of relevant domain model.

So very true and this is actually my biggest complaint with MSDN nowadays. It's so difficult to built a mental model of what's actually going on, which makes the documentatino difficult if your needs aren't exactly what the documentation is describing.

I don't know when this phenomenon started but it drives me batty.

Everyone wants a quick fix these days, in all parts of their life.

How to do X in [an hour, a day,one week of lunches, 30 days.] Heal yourself from X in [an hour, a day, one week of lunches, 30 days. ] Eat/Dont eat this get slim in [ one week of lunches, 30 days, 60 days]

A long time ago I studied martial arts (Karate). Our structure went up to the master in Japan. Once you got past the orange belt, the only way to progress was when the master was visiting. the master also decreed that you had to have a belt for min 1 years, in brown 2 years. in black 4 years before you could try to graduate. He said people needed to grow into their skills and mature.

I haven't thought much about that until a few years ago a colleague told me her daughter had just gotten her first black belt. Knowing her child was no more than 12 that seemed odd, but she had studied hard for almost 2 years.

That seemed like some form of fast-food martial arts.

By pure coincidence I met the son of my previous master at a train . I knew him but the last time I saw him he was still a kid. He was Japanese as well but he spoke excellent English. Something his father had no interest in. He had taken over from his father and was now the master. We talked a bit his dad, the clubs. I mentioned this rapid progression that my coworker's daughter had done. He leaned back and laughed a little.

"Ah, we call those dirty white belts"

A little like coding bootcamps I think.

Manuals in the era were in general pretty good comparing to today’s open source software standard. Microsoft C++ has about 6-7 dictionary sized books as the manual.

Love that era. I’d definitely pay more if say Jetbrain has these kinds of manuals. But it doesn’t make sense nowadays to have printed manuals, not only because of the cost, but because nowadays people don’t need to read books about language specifications.

I do miss books.

For a while I was a contractor at a hush hush place. We had extremely limited internet access and even stronger rules not to use it. No cellphones, no Wi-Fi, no BYOD.

It was like going back to the good old days with books. We were given the opportunity to order books.

I adapted the best of our team but probably only because I am old.

We had one good old fashioned corded phone, which was for internal calls only. It was not hooked up to anything "outside".

We were given a number that our nearest could call in on.

The number should be connected to some semi anonymous front desk somewhere.

It was to be used (only) in an emergency (they emphasized that)

The routine would be that a member security detail would come to notify the relevant person, escort that person to a room with a phone, that the front desk could route the call to. Someone might or might not be listening in.

As far as I know nobody tried it.

I dont know if the routine is still the same now. I would guess that younger developers would have a much harder time adjusting now than back then.

Ah, a place I'd love to work in.

Anyway, nowadays software development, including tool development takes the path of quick iteration so manuals are not very relevant anyway after a while.

Does IBM still give paper manuals to system programmers? Maybe the mainframe business is old enough to retain certain traditions.

The first Turbo Pascal IDE, with compiler and debugger, ran as a .com file so all the code and data had to fit in a 64KB memory segment.

Reply on news.ycombinator.com