How I, a non-developer, read the tutorial you, a developer, wrote for me | Hacker News Reader

How I, a non-developer, read the tutorial you, a developer, wrote for me

anniemueller.com

931 pointswonger_444 comments

Can't recommend this approach highly enough: have someone with minimal expertise go through your docs with the goal of achieving the goal of the docs. Sit next to them or screenshare. Do not speak to them, certainly do not help, just watch. Watch them fumble. Watch them not know what to do. Watch them experience things you (the author) didn't, because you already had xyz configured on your machine and you forgot users won't have it. (even watch them pretend to know what they're supposed to do when they don't really).

If the user achieves what they need with minimal stress/guesswork/ambiguity, the docs pass. If not, note every single place they fail, address each one, and repeat with a new user.

I've used FAANG docs that don't come close to passing the above criteria.

I've been incredibly grateful my org set this high bar. Especially when using docs for critical tech I only use from time to time (where I forget lots of it). Saves meetings, support inquiries, and video calls, because the user can self-serve.

I seem to have this problem a lot with Apple’s docs. So much of it is like

    Nargflargler: Flargles the narg

You need to do something besides repeat the name in the definition.

This is just one example of how metrics can distort things, of course. Someone in management said "We want 100% documentation coverage of every method," so the staff dutifully wasted everyone's time by writing "setDefaultOptions: sets the default options". It's the kind of thing an LLM could have done better, and if you know my opinion of LLM's, you'll know that's damning with faint praise.

My own bete noire here is MSDN. It's full of overloads like "Foo(string parameter, FooOptions options) - actually useful documentation. Foo(string parameter) - does Foo with default options." But to find out what the default options actually are, you have to find another page, probably the FooOptions constructor. I wanted the default options to be mentioned on the "Foo(string parameter)" page, and they so rarely are. (A few pages are better, thankfully).

Related to this is the omitting of units. I encountered something like this in the Android SDK (years ago, dunno if it’s still like this).

    setFontSize(float): sets the font size.

Cool. Sets the font size in what? Points? Pixels? Device-independent pixels? Which of the 12 different types of measurement Android supports is used here? I can’t remember exactly what it turned out to be, but I know it wasn’t the unit I expect for fonts (points).

AVMetadataKeySpace

A structure that defines a metadata key space.

source: https://developer.apple.com/documentation/avfoundation/avmet...

Not quite what you're talking about but this Apple doc page has always amused me: https://developer.apple.com/documentation/contacts/cnlabelco...

I have to assume that there exists some language where that relationship is described in one word, but it hurts my English-oriented brain.

Or with Xcode, go to fargler settings click on narg screen. Took a year just to figure out most setting screens

Apple documentation reminds me of an argument I got in with an elementary school teacher over a textbook… it went on for weeks

> A prepositional phrase is a phrase with a preposition in it.

> A preposition is a word in a prepositional phrase.

One problem I remember from (briefly, fortunately) dealing with Apple APIs is wondering incessantly why every API (I was looking at) started with NS. Admittedly these days any AI would tell me it stands for Next Step. But if you are creating a new thing with a quirk like this please explain it once, in a place that's easy for the student to find.

Triangle theTriangle = new Triangle()

Lives rent free in my brain.

The issue here is that people are treating reference materials as tutorials intended to cover your exact concern at the moment. You are expected to know what a narg is and what flargling means. In more real terms, the documentation for screen savers https://developer.apple.com/documentation/screensaver?langua... won't explain what a view is, what subclassing is, or what a Rect is. Those are required knowledge to consume the documentation and it's not a documentation failure that this is true.

I want a linter against this. I have a hatred for those kinds of docs, they take up screen space, its worse than nothing.

then how would you descirbe a nargfargler?

dont say.. boop?!

God I hate this so much when I google some unknown word and it's just: "Nargflargler: When someone narg flargles something"

> Do not speak to them, certainly do not help, just watch.

Sounds simple, right?

I ran usability tests at a past company and have seen people who were incapable of blurting out explanations, pointing at the screen, even audibly grunting or whining to themselves when the participant made an incorrect guess about what something meant. One even grabbed the mouse.

Having a neutral moderator can help as it allows the people who made the UI/docs to stay on mute or on the other side of one-way mirror.

But I'd still suggest learning the "just watch" technique. If you master that and wish to take the next step, look up "think-aloud protocol".

I mean, if the test user can't figure it out at all, how is the rest of the UI/documentation supposed to get evaluated?

> You can also record it to show them later, but for various reasons it doesn't resonate quite as strongly when it's not live.

Yeah, because it's wasting my time having to watch people who literally have never heard of something as basic as keyboard shortcuts. It's fine if I actually have the time to explain to some Gen Z kid how Ctrl+X/C/V works, but being forced to sit around and watch someone with that level of non-understanding of how a computer works when I got a full backlog of shit to do is just agonizing.

With a video recording, I can at least go forward and see where they actually have problems with stuff that is in my influence and skip over the utterly boring moments that are just wasting my already limited time.

This is our documentation workflow as well: Write it, and then have someone less or not experienced with the system execute the runbook. Also, encourage everyone to work on refining and improving the docs, because after 5 years with a system, I will have blind spots someone less experienced can point out.

On lesson I've learned from that: It's a lot about managing confidence of the user.

To do this, the instruction of "invoke this shell command" is now usually accompanied with a number of sections collapsed by default: How does a successful invocation look like - especially if it contains "ignorable warnings"? What errors could occur, and are they fatal or can they be fixed on the fly? Some more complex shell-stuff is often also accompanied by an explanation of what all of this is.

And yes, this means that sometimes one step in a runbook has a page of documentation if you read it all. But we've found that this helps a lot during onboarding new team members, as by now, a lot of the standard runbooks are also a prety good introduction to the quirks and quarrels of the normal tools we use.

A good first exercise for new hires! (And I say that as having been both a new hire who's updated the documentation after trying to execute it, and as someone who's guided a new hire when the documentation proved inadequate.)

Any kind of documentation has a target audience. Your test is very valuable if and only if the target audience is a total beginner. Of course it's still very hard to write good documentation even if you have identified your target, but having someone totally illiterate on the subject matter review your documentation is as useful as if I'd have to review a PhD thesis in quantum physics. It just doesn't make sense (trust me :).

Writing documentation is hard. Start with: Who am I writing this for?

edit: I may have misunderstood OP's "with minimal expertise" for "total beginner". They're two different things, absolutely.

For most public documentation, you don't get to pick your audience. You think you'll have people with certain experience, but then it turns out you're wrong. Usually a lot of the time. And even when you're not wrong, having the steps essentially from scratch listed out reduces the number of times people get stuck, because they think about things they may have missed.

I was gonna write something similar. Know the audience. I've also come to the conclusion that "total beginners" (and certainly "minimal expertisers") didn't nowhere to read the docs anyway so it didn't matter.

In other words, people who are used to reading docs can read (good) docs just fine.

Yes, of course, good docs are a must. They are critical to success. But not all docs have to explain how to use a right-mouse button.

Perhaps in addition to a description of the expected audience, it might be an idea to list some assumptions made about the reader? e.g. has installed software previously, confident with bash commands, &c

The experts are likely to be skimming and interpolating your doc, so they'll get through it but you won't know why. You won't know if your doc works, or if it even addresses the subject matter. This is also true of academic papers.

My mom taught CS in the 1980s, and told her students on day one: "Computers are stupid, they will only do exactly what you tell them to do, not what you want them to do." Program code is, in a sense, a tutorial for an utter beginner. The benefit of coding is that you can do the "beginner test" over and over without wasting anybody's time, so you know that the computer will get through it. But an expert (including yourself) might read that code and never see that it does or doesn't work.

It's crazy how bad most onboarding docs are for corporate teams. I think it's a great first look the culture and how much of a hassle the role will be. The last three teams I've joined have been brutal with how little was documented or how out of date the docs that did exist are. I've had to spend up to two weeks tracking people down to find out what access group I need for our logs, deploy pipeline, etc. and I end up writing up a new doc that's good for its point in time, immediately becomes out of date when someone adds a new system or access group but doesn't document it anywhere. The one team I was on previously that got me everything I needed in about two days was great, but it's sad that this isn't the norm. Everywhere else has been pretty hostile to getting set up, and the poor onboarding experience has been a preview of the developer experience. My current role is standing up a new devex team which I'm hoping turns the tide here.

It's not very crazy to me. Most corporate teams are overrun with feature creep that "is very simple" (i.e. it takes 3x as long as estimated, because the codebase is a mixture of overengineered spaghetti for that one customer with edge-case requirements and legacy, combined with tests that are meant to be run in a jenkins job which takes 4h to complete).

Then, the engineers are expected to write the docs in between these tickets, and doc is seen as something "to be done within 30 minutes" - of course the docs will be comically (or tragically, depending on your perspective) bad.

Most people have 0 idea on how to write good docs, so in 30 minutes, they write stream-of-consciousness docs and return back to the ticket hell.

if you're writing a new doc to "fix" this situation, you're commiting three crimes: 1. all that old documentation still exists, misleading and confusing people. you've now made the problem n+1, 2. there's no strategy to keep your new document from turning into an old, stale & out-of-date document for the next person, 3. you've addressed the wrong problem (nothing's documented!) and feel like you're superior to all the jerks who came before you.

>> My current role is standing up a new devex team which I'm hoping turns the tide here.

I'd love to know what you're doing different that can help with this problem. Writing more, new documentation is unlikely to be it.

Sometimes I wonder if it's a respect or control issue. I once worked in a non-technical position that interfaced with a complex order management system. We were given zero access to documentation and had to rely on trial-and-error and the reverse-engineered model held in the head of one specific supervisor. I'm almost certain that certain errors that appeared over and over were caused by us temporarily clearing previous ones incorrectly. This was especially frustrating because we were 2nd shift, so dealing with those errors could mean the difference between getting home that night or getting home the next morning. It was hard to tell where along the line between, "They're not sophisticated enough to make use of them," and, "We don't want our processes leaking," we fell, according to the higher ups.

A technical writer's first task is to start the document that onboards the next technical writer.

Reading through bad setup docs is 10x more stressful when they are part of new employee onboarding.

I’ve always advocated for new employees first contributions to be fixing problems they had in these setup materials. They are coming in with fresh eyes and no context so they are the best possible reviewer

My first ever software developer job, I was hired with basically no knowledge or experience to learn (I was very lucky). I knew MS-DOS command line pretty well from my childhood, but hadn't ever used POSIX. I was given a macbook air and some docs to follow.

Trying to follow the docs, supplementing with a lot of googling, I somehow managed to remove the tar program from my system. This broke literally everything. Had to stop halfway through the multi-day process to do a clean reset and start over from scratch.

I worked with someone who was great with this. They’d go through the docs and do exactly what was said, document where problems were hit and then repeat from scratch again and again. Seemed slow but their docs were excellent and I’m sure it saved more time having him hit each thing once than everyone else hitting them loads.

I am that guy. I will also say from experience: It does not pay. Never once has it been ack'ed in a year end review (which controls bonus, salary increase, and promotions). As soon as a manager sees you as "The Wiki Guy", they take you for granted. As I grow older and more cynical, my view on internal docs: (1) Write them for yourself. (2) Write them to make people go away when they ask you questions ("Did you search the Wiki?").

Funny enough, we had a hell of a time running a helpdesk where we designed the docs -- many of which I wrote myself -- to be executed exactly as written.

Guess what humans hate to do? Especially the smart ones, which of course you want to employ on your helpdesk? They just would not read the damned instructions.

I think this was because many of the instructions were dumb. We were explaining decades-old bank stuff. It didn't make sense, but it's what you had to do! So these guys tried to 'fix' it, and in doing so, broke it.

The whole support model was predicated on this idea that the 3rd level guys would write stuff that the 1st level guys would slavishly follow. It never worked.

We called this the “receptionist” test decades ago at the small company I was at - after we though we were done we’d give it all to the receptionist and ask her to use it; and we’d hang our head in shame at everything we forgot and head back.

There’s a version for kids to show the details of how to program by literally interpreting steps. https://youtube.com/watch?v=n4rh2jD8OkY

You can achieve a lot of this by creating a blank virtual machine with "just the operating system" as a starting point and stepping through your own instructions from there.

My ideal state is that for my kind of .NET work, it should be sufficient to simply install the latest Visual Studio, check out the Git repo, and press "play".

That's not always possible, so then the exercise becomes to simply document each step, ideally with both English words and a CLI snippet.

I agree that testing from a vanilla machine is important.

But there's also that your language to the user doesn't necessarily say what you think it does. You can't read it from the position of someone new. Only someone new can.

And a set of commands to paste to CLI isn't the full extent of what we usually mean by documentation.

Yes, more of this!

I am a big fan of the "clone, F5" and it should run. If specific steps are required, I put that in a setup.ps1, and the details in the readme.md.

If the project has external requirements, I put a link to the repos, which should all be... "clone, F5"...

Indeed, snapshots are an amazing friend for this.

Or let the Junior rewrite the docs while they're scratching their head, and push an update once they've figured it out.

I'm a senior designer who often contributes to front-end code when it's convenient for my client.

Fixing and updating the README when I join a new team and set up their dev environment is always extremely well-received.

Wow, way to double down on “I really hate everyone who doesn’t have exactly my skill set and experience.”

I'm a Jr. sysadmin at a medium sized software company. Whenever I document workflows for our users, I have two colleagues of mine who have no connection to IT work through them and add the small gotchas they asked me to the docs.

It saved me a whole bunch of headaches for when other users get enrolled in these workflows.

I've been doing some cal/QC functions recently after years not touching it. Since I last did it I've forgotten some of the knowledge that is just assumed. The answers to my questions are documented, but not in a places that is accessible from the production side and has lived as community knowledge in production. I've been making a list and updating the documents to fill in some gaps.

Unfortunately some of the production people aren't comfortable enough pushing for changes in the documentation so some of my job now is to ask what they've noted and get it added.

I'll go against the grain and say that fumbling is how you learn. The easier it is to get to the end of the tutorial, the less you learn in the process. If you learn math from a bad book, you have to organize your own notes, to untangle the mess. If it's laid out all neat and clear like a straight highway, you never wrestle it out with the concepts and you don't learn.

That's something I came to accept as well - deeper understanding will only come from challenge. Unfortunately, there isn't always the opportunity to let people fail, and that opportunity is definitely not in a set of reference docs.

I like to always provide a docker image which can be used to execute whatever solution I'm developing. Most of the time the docker image isn't even used, but it's an important exercise because I'm forced to run my solution on a fresh system, so the resulting docs will invariably be more complete, and it also documents the dependencies in a way you can easily verify.

This is basically the user testing approach as described in "Don't make me think" by Steve Krug. You can use it to test usability of your applications as well.

I think the JavaScript ecosystem did a great job at this. Take a look at the documentation of React/Vue/Svelte; it is fascinating how they make it so accessible, both for newcomers and experienced developers in the field.

In contrast, the Java ecosystem has been really bad at documentation in my experience. Most of it is just explanations of function signatures, without any words on how those functions work as a whole system. The situation is even worse on Android, where there are dozens of standard APIs to achieve the same functionality.

Those are references, not tutorial. They are there to refresh your memory. Usually you look for code examples or a guide for learning how those work (even AOSP apps if needed)

Don't speak to them or help them at all?

Suppose they get stuck on the first step in a multistep procedure. Do you just let them keep flailing on that step for however long they are available, so all that you learn from that entire session is that the first step needs rewriting? Or do you end the test and let them go, again learning nothing beyond that the documentation for the first step sucks?

Wouldn't it be better at that point to help them on to the next step and then continue on having them test the rest of the steps?

> Especially when using docs for critical tech I only use from time to time (where I forget lots of it).

An important point easy to lose sight of when writing when that knowledge isn't lost yet

I was talking to a friend who is a beta-tester for crochet patterns, the business owner sends out a pattern to a trusted group and the get feedback on the descriptions and the work and any things that would make it easier before they put it up for sale.

I do think a lot of developer tutorials and documentation don't take into consideration that many people might not have a common understanding of terminology especially if the reader is coming across this problem or process for the first time.

I am stuck in an organization for some personal reasons.

The first thing I noticed when I joined was the culture of "Please ask when something is not clear". After was given a quick overview in person.

You guess: almost everything is unclear. A mess. Need to ask a lot. Task descriptions, purpose, reasons, whys, wheres, what does this comment mean, why are these things contradict each other, and so on, and so on.

And except asking KG, usually the answer is: ask XY. Or KG.

People always busy, always in rush, give a condensed answer raising the same amount of new questions that it answers.

When KG is out, productivity slows down.

And all this beyond the usual in a meeting, out with customer, on holiday, sick, the children is sick, held up in a traffic jam, car broke down, need to finish project P so schedule something for next week, and all those kinds of common things making the relevant person unavailable when "something is not clear".

And beyond the forgetting 4 things of the 15 new info given by the time we are finished with the converstaion. No written trail to look back at.

When 3 person paint a complete picture then all above happen three times in a row, or in a never ending loop.

Productivity suffers, quality suffers, I will leave as soon as I can.

Positive things? Probably that the expectations are low. And they pay well. And by now I am irreplecable in a local subset I was hacking together (I do not call it work or development), not even KG can help others there! I will leave on my own terms (as usual, unluckily).

So doing the basics of product design? :D Sounds like a good approach! Sadly user tests or other forms of iterating are often overlooked.

The golden rule: Plan -> Act -> Test -> Repeat

I started a company to do exactly this a few years ago, and got to work with amazing companies testing their developer experience.

The problem is not the docs, it's Conway's law. One team designs the API, the other team designs the portal, and another team designs the SDK. The user has a holistic experience that cuts through each team.

That, and the docs are usually written first by the most technical person around, who has a hard time sharing the world view of a noob.

Fully agree. Good docs are essential for scaling a team beyond the first few hires. I always make a point of filling in all the gaps I had to gather myself during my onboarding, and ask the next hire to do the same (and carry it to the next hire, and the next) this helps keep the docs up to date with the relevant knowledge since it’s always being filtered through the lens of a brand new computer and a dev with minimal context.

Thoroughly agree. Where I come from it's called "shoulder surfing". It is really important to not help.

People here are talking about it as if its merely a problem of wrong target audience when the problem is a lot of docs are straight up lies. The example setup steps and configuration in the front page itself fails. That's what makes me wish I could shoot someone or something.

I absolutely love this approach. It is in the spirit of https://1x.engineer/ and it should be applauded.

> If not, note every single place they fail, address each one, and repeat with a new user.

Might not this loop be invoking Goodhart's Law?

What is "address each one": are we just changing that document, or are we (also) changing something in the system that the document is about?

If no newbie has any problem following the document, is that still a good document for non-newbies?

If no newbie has any problem with the system that the document is about, are there any downsides?

> have someone with minimal expertise go through your docs with the goal of achieving the goal of the docs. Sit next to them or screenshare. Do not speak to them, certainly do not help, just watch. Watch them fumble. Watch them not know what to do

And if you have access to user experience researchers, go talk to them! They are experts in running this kind of scenario, and can help you avoid all the pitfalls that might bias your results

Totally. Something that I see a lot is software that tries to read a config file during startup that bails out (sometimes with no error message!) if the file doesn't exist. Or tries to write the config file into a directory that doesn't already exist.

I'll get things working locally first, but I always have to test it in docker/other fresh test env (Vagrant), just to be sure I haven't committed the same sin myself.

We do this in game development .

Watch someone play the game for the first time. Don’t interfere. See if they can figure out how to play.

Play testing is the most important part of game development. Indies who struggle to come up with concepts are really sleeping on this. If you run play tests well enough your roadmap will almost write itself. Players will do and ask for things that you would never dream of.

I think an intense culture of playtesting is why valve software puts out games so rarely. Their new strategy seems to be to keep a title semi-secret for years while a small army plays it full time. If Deadlock makes it to market, it is almost certainly going to be an acceptable game to most who are even remotely interested in the genre.

I wonder if we now have the tools to build unit tests for docs now; an LLM should be able to take on the persona of a beginner try to follow your doc. For bonus points use a dumber/older model that can’t have trained on your API.

Basically, ergonomic testing, but for your doc instead of your software.

I've written a lot of docs, and one big issue I saw play out over several years was watching the overall skill of the team members drop. They were told by their manager to use the docs, which they did, and then seemed unable to think outside the docs when needed. For tier 1 support roles, I think the docs were helpful to get them going, but it seemed like the docs acted as a crutch for most of the team, to never be able to grow in their role and move up to tier 2. I'm not sure how to solve for this problem.

I think that always depends entirely on the docs and how people are instructed to use them.

From a software engineer standpoint, we have a larger collection of docs for the internal platform we run. The docs for other engineers follow the diátaxis framework [0] for documentation. Its the best approach we've found so far and the overall questions and guidance my team needed to provide reduced by a significant margin while the PRs we know receive have increased in quality and quantity.

[0] https://diataxis.fr/

I think that you are interpreting this outcome as technology-wise negative. Instead, I will offer a commercial positive: If the docs that wrote are so great, then you can hire lower skill, cheaper support staff. Training is also cheaper (because of docs). If I was senior IT mgmt or biz mgmt: That is a win.

    > never be able to grow in their role and move up to tier 2.  I'm not sure how to solve for this problem.

I have a selfish answer. Who cares about staff that don't improve. Really. Read that twice. Leave them behind in the dust. I am always blown away when I meet someone in my career and they have been doing some shitty support role, and they have barely progressed (career-wise or tech-knowledge-wise). Who are these people? Everyday, they dig a hole, then a 4PM they fill the hole. Rinse and repeat! Someone who is smart enough to "figure it all out" and write docs should be promoted, or moved to another support team to repeat the same pattern.

I always write my own notes when setting up to "fill in the blanks" of the guide, then I create PR with them.

this works great, if, they speak out their thoughts verbally, in real time.

are you interested in giving a talk/presentation about this

> just watch.

You need to be brutal with yourself for this, and understand you're chasing popularity, and not necessarily revenue.

It's good to be popular with your users, but if your users are not your customers...

> I've used FAANG docs that don't come close to passing the above criteria.

... FAANG is an excellent example of which; Because their documentation and code is so bad integrations always take longer than anyone can estimate, this actually discourages managers from considering a second integration.

That is to say it's not necessarily good business to "pass the above criteria" and I think it's important to remember that.

Ask the guinea pig (read: victim) also to think aloud.

LLMs have mostly eliminated the need for this. They are quite good at explaining things.

Correction: They are very good at writing seemingly-good explanations. The explanations may or may not be correct.

We're quickly approaching the point where you can have an LLM do this, and if it passes "the doc passes", if not, time to edit.

I was gonna say this. Really good idea. Having an LLM go through the docs and try to implement something. Challenge would be to prevent it from using any prior knowledge or experience, depending on the docs target audience. Good prompt is essential.

Without AI, it was really hard to get to understand some docs. Today if you don't use AI for these situations shrugs

Most cases it is not that docs author forgot users wont have same toolchains. Simply do not bother reducing config files to share just source code. Indirectly pushing users to make use of same tools.

Hopefully in 20 years no one will be going to check the source code of anything, and programming is elevated even more.

50 years is crazy amount of time, to stay this primitive. Tech shouldn't just evolve for end users.

Most tutorials are not for non-developers, they’re for other developers who are also in the ecosystem. They’re more like academic papers (peer-to-peer communication of new discoveries) than they are like a pop sci book or show meant for a general audience.

And that’s okay! Great even! As a fellow peer I benefit greatly from those tutorials. Sometimes even from my own notes published and forgotten years ago.

This is why courses and other structured learning materials exist. Beginners have to be nurtured through lots of context that builds up slowly. If every article had to start from scratch, we’d never get to anything interesting. By the time we got to the interesting bit after 30,000 words of preamble, you’d be long gone as a reader.

And the very next reader would complain that the 30,000 words were not enough introduction to the topic. They needed 40,000.

> Beginners have to be nurtured through lots of context that builds up slowly.

My son is 17 and very interested in programming. Had to explain to him public, private, internal, and also static the other night.

I then joked, you should ask your teacher about recursion tomorrow. He's with his mom this weekend, but I'm anxiously awaiting hearing how that went.

Ah, the infamous public static void main(String[] args). Hopefully the next generation won’t need to learn all those concepts up front with the introduction of instance main methods in Java 25.

https://openjdk.org/jeps/512

He’s starting with Java? I wonder if that’s the right language to start with. What is he most interested in doing? Anyway thanks for nurturing the next generation.

> Had to explain to him public, private, internal, and also static the other night.

Access modifiers are sort of a dying breed in a lot of places aren't they? We use Go, so we're obviously still using the two it comes with, but it's public vs module only and fairly intuitive. Every other language we have in production, doesn't make use of access modifiers. Similarily while static is a thing in Python, it's hard to see what advantages it brings compared to a free function if you're using a programming language that doesn't require you to have object instances to call non-static functions. Obviously access modifiers will stick around in a lot of organisations, but there will be plenty of jobs where you never have to work with them.

The way Go handles modules, is frankly one of the few language feature of any language I've ever worked with that I wish was in every language I work with. It's so easy to use and so hard to mess up. Ok, I guess it's not hard to mess it up, but it's not intuitive.

Maybe he and his teacher are caught in a loop ;)

I think Java is dying.

If you want to teach algorithmic thinking, teach Python.

If you want to teach hardware and low-level systems, teach C.

"Most tutorials are not for non-developers"

That has been repeated in the comments many times now, but the very headline says that this tutorial was indeed also intended for non developers.

Like some open source Github project that the author merely wanted to install, not starting to mess with the code. Basically, it is complaining in a satirical way about installation readmes, that maybe they could be made easier, that also non developers can follow some simple steps. A complaint that I can very much agree with, even though I am a developer. But so often little steps are left out and when that happens in a area you are not familiar with, then this can mean lots of wasted hours.

> "That has been repeated in the comments many times now, but the very headline says that this tutorial was indeed also intended for non developers"

tbf, that's not how I read the headline. The headline is: "How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner"

The author is a beginner, which puts them in the field - so the parent comment is valid no?

> it is complaining in a satirical way about installation readmes, that maybe they could be made easier, that also non developers can follow some simple steps

See I missed that context :D

Installation readmes are an interesting example – they shouldn’t exist. Put that effort in an install script instead.

If you want me to mechanically follow some steps, perhaps with a decision tree attached … computers are really good at that!

  > They’re more like academic papers (peer-to-peer communication of new discoveries)

This made me laugh because I frequently see HN comments on arxiv papers claiming things like the authors are trying to show off with their math rather than the math just being an effective communication tool. Honestly, if anything, papers are written to too broad of an audience and we get these 10 page papers that could be communicated in 3. I'm unsure if this has been a good change. (Yes, I read the whole comment)

Just because you have access to the text doesn't mean you're the intended audience.

Probably a good thing for us to all remember here on the interwebs where everything is accessible but written for no one

> Most tutorials are not for non-developers, they’re for other developers who are also in the ecosystem.

To me eye, most tutorial nowadays are so a developer can put "made public contribution to <X>" on their resume or quarterly evaluation rather than helping other developers.

I'd be even happier if the original writer would simply come back 3 months later and retrace their own directions. That would make the tutorial vastly better as they will suddenly see all the little things they left out.

I guess I disagree that it's a good thing.

As a developer, I think most documentation is terrible both for developers and non-developers alike. And if you write your documentation so that it is useful to non-developers, it's still useful for developers.

There's no downside to writing accessible documentation, except that it requires a modicum of skill and effort. That's the real reason it's so rare, I think.

I also disagree that developer documentation is like academic papers. The ways they fail are almost opposite: academic papers are overly long and overwritten, because the authors want to be very careful and complete. Developer documentation is too short and hastily written, because they often don't care if it's helpful to anybody else.

The end result may be the same: neither are useful except to a small number of experts: the people who could probably do it themselves already, and thus may not even really need the write up to begin with. But that's a failure, not a feature to be celebrated.

> Beginners have to be nurtured through lots of context that builds up slowly.

I agree and when I write for such an audience, I try to be detailed and build on a proper story that they can follow through.

I do have a complaint about attempts to smoothen the DX which a lot of projects do that results in something which helps only the absolute beginner. Logs are not easily accessible or missing. It's not easy to cut/paste or grep for errors in things etc. Basically, many of of the familiar tools and techniques which people have used to find their way through things are replaced by poor substitutes in the name of making the DX better. This, I don't think is a good trend.

I find that a lot of project homepages (or GitHub README.md these days) are riding high on "if you're reading this, you already know what this is for" energy.

What I would give for people to approach documentation in a more empathetic way; tell me what something is for, what problem it solves vs other competing solutions such as X or Y, whether it's still the best solution or in maintenance mode because another tool has become dominant.

Give me the tools to construct my own pros and cons matrix, without assuming that I'm an expert. Put five minutes into asking yourself "what questions are people likely to have, even if they aren't sure exactly what to ask" and write that down.

I'll never understand how someone can spend months or years of free time building something, but then actively sabotage it by not making it easy for people to realize that they've found what they are looking for.

It's also really valuable to keep perspective on the different kinds of documentation. https://diataxis.fr/ is a really solid starting point for anyone aspiring to create better docs.

This issue with READMEs in particular has driven me nuts for the decade I've been doing ROS related robotics stuff. So many repos where the only surface clue (i.e. before diving into the code) of what it does is your interpretation of its name.

But I'm pretty sure it's universal, like you allude to. And not just open-source; but at work, too. I feel like I'm the only one in my company that makes PRs to edit the READMEs to explain what a repo is for, and what repos it might relate to. (I was much happier in the past when we had a couple mono-repos; now the trend is every little project gets its own undocumented repo, alas.)

Lately I’ve been asking Cursor “what does the program do?” Was actually pretty helpful as a starting point.

I echo this sentiment. Whilst I completely understand that developers are doing this in their own time and largely for no other reason than it being a labour of love, it would really help lower the barrier to entry.

Oftentimes when the tool is typically used as part of a useful stack, the other components have documentation that can also be difficult to decode. So it becomes an order of magnitude more difficult to understand.

What I really really want to read in a README is *why* did you build this? The "rationale" section of a README is almost always the most interesting part.

I can read the code, I can understand how it works but I cannot know why you decided to tackle this issue a certain way.

There was a project posted here once that didn't even bother saying what the thing even was!

Most technical writers (and communicators in general) have an insufficient appreciation for the curse of knowledge.

This takes me back to running a World of WarCraft guild as a teenager.

We would organize "raids" maybe 3 to 4 times a week. It involved getting 40 of our guild members from all over the world to sign on at the same time, and spend hours facing off against dragons and other monsters inside dungeons. It was the most fun I'd ever had in a game, but it was also instructive. The battles were famously difficult and required a ton of coordination and strategy, and even a small mistake could get everyone killed. So our policy was that everyone in the raid had to sign onto our Teamspeak server, which was basically an audio-only Zoom call where my appointed officers and I could give orders and dictate strategy.

I very quickly learned an important lesson in communication: assume the worst. Surprisingly (to me at the time), most people who don't understand what you're saying won't stop you to tell you they didn't understand. And so I came to live by two rules:

1. If it's worth saying once, it's worth repeating. Assume people are only half listening, that they're distracted, that they're not paying attention.

2. Don't assume people know what you know. In fact, while talking, keep a second thread running where you explicitly ask yourself, "What am I saying that my listener might not know?" Then explain it.

The more I followed these rules, the better we did on our raids.

But even long after I stopped playing WoW, both of these rules have been helpful. Especially the second one, which helps overcome the curse of knowledge -- the phenomenon that occurs when a person who has specialized knowledge incorrectly assumes that others share in that knowledge.

Thinking about the curse of knowledge when communicating basically becomes second nature after a while. And then it becomes obvious when you observe other communicators who don't care about the curse of knowledge. They confidently launch into stories using obscure terminology and acronyms that nobody understands, without a care in the world for their listeners' understanding, they don't notice at all that nobody understands.

I remember being in a raid guild. The guild leader was this random 18 year old kid. I remember noting that this kid was expertly herding cats, many of whom were much older professionals, with absolutely zero direct authority, across multiple timezones, and getting them to not only agreeably distribute valuable loot, but also coordinate them through intricate boss dances and more intricate event scheduling. I thought it was a real shame that this wasn't direct evidence that he should be hired into a people management role immediately.

I keep saying that anyone who could run a 40-person WoW raid is almost certainly going to be a top-tier project manager.

Those raids are like herding cats. Distracted, teenage cats with connectivity issues.

And they say WoW was a waste of time.

One of the things I've tried to teach people I've mentored over the past few decades is the principle of "Sharing is better than assuming." If you know something, share it with other people. Don't assume that they know something. If they do know, and you tell them, then you've only really confirmed what they already knew. If they don't know whatever it is you've helped them immensely and made whatever it is much more accessible.

Occasionally people will complain that you're being verbose and adding detail that they didn't need but in those cases you can usually just say "oh, that's just in case a [junior|manager|customer] sees it." People don't mind if you flatter them that the explanation was for other people.

It applies as much to development as it does to investment reporting, people management, delivery management, etc,

I have encountered a number of people who exhibit startling hostility at being told something they were already aware of. While I cannot currently recall a specific example, I strongly suspect I have previously felt this way myself.

While sharing may be better than assuming when only considering the local optimum, if your signal to noise ratio is bad enough, you will face an impairment to communication that simply wouldn't exist if you had been more selective.

When someone makes a search and lands on your tutorial, you are not giving him unsolicited information.

> One of the things I've tried to teach people I've mentored over the past few decades is the principle of "Sharing is better than assuming." If you know something, share it with other people.

Definitely agree with this in principle. My son and I play pool (billiards) competitively. As you get better, almost nobody shares any tips because it's very competitive. I've taught him to be better than that and we have a great league team where everyone is helping the others grow.

In the mentoring (not just teaching) realm, I like to guide them into asking the questions that gets them to the answer they're looking for. When the connections in their mind light up, it's amazing.

> If they do know, and you tell them, then you've only really confirmed what they already knew.

Not necessarily. This opens you up to accusations of engaging in "mansplaining" which has broadened in definition over the years.

In addition to this, it opens you up to being thought of as a "know it all".

It's far safer, as far as office politics are concerned, to put on your coworkers the burden of asking you to clarify/explain/teach.

Would asking them if they already know or would like something explained be the best thing to do (rather than assuming one way or the other)?

Most tutorials aren’t for non-developers. They’re not for developers, either. They’re a bunch of prose I want to skip, and then I finally get to the steps I’m really looking for, but the author left one out, or assumed some weird development environment or IDE I’m not using, and I have to give up and go back to Google again.

The problem is that writing is hard, because it’s for people outside of your head, while you’re inside of it. As toddlers we learn that our senses aren’t immediately accessible to other people, but many of us never master the art of remembering that knowledge and experience inside our heads isn’t available to you, the reader, until we write it down.

Oh, and maybe if folks thought “cookbook” instead of “tutorial” when they’re writing, the result might be organized better for the rest of us to use, and less likely to become useless after the next point release.

Ironically, online recipes of the cookbook kind are actually much worse for meandering and irrelevant prose than programmer blogs are.

This is primarily the reason why I stopped writing books and started making tutorial websites. There are so many interactive tools like <abbr> element that can make tutorials accessible to more people without inflating the content itself.

I'm still incredibly annoyed how constrained our web knowledge is to the feature set of ancient paper technology. We can click, hover, collapse areas, play videos and react to user actions yet most content is just these lazy walls of text. Event OP here uses footnotes that just scroll to the bottom of the page adding very expensive context switch for the reader rather than take advantage of the web browser capabilities like hover or modal pop ups.

Hello, I am just now trying to upgrade my blog. Can you please point me to sites that do this right?

An extreme example would be gwern.net -- specifically you might want to read https://gwern.net/about and https://gwern.net/design

When writing documentation, you need to establish a baseline of required knowledge and skills for your audience. You can choose any level, but deviating too far above or below that baseline will inevitably frustrate some readers.

When this happens, you can either make excuses or focus on solutions. Problems can be difficult, but with modern tools like AI systems, Google, or even books, it has never been easier to overcome them. If you don’t know what a Shoobababoo is or why you should use the quagmire instead of the hoobastank, you can look it up. Ideally, documentation would contain every answer with minimal need for external knowledge transfer, but the world doesn’t owe you that convenience.

> you need to establish a baseline of required knowledge and skills for your audience

So many guides for setting up like... "control system simulation" or "industrial automation compliance test-bench" start with "double click the exe and press next".

Baseline for expected knowledge for the user of the guide is SOOOO important.

"What is an exe?"

I write stuff for our internal teams and it's usually for sensitive systems where you can cause a lot of problems if you make a mistake. I will often start the doc by saying "This assumes you know how to use x, y, and z. If not, then you probably shouldn't be doing this." We limit access already, but some of these could be used in a DR scenario by someone who is not super-familiar with the product. I purposefully will not explain certain things because if you can't figure those out, then you shouldn't be doing these steps.

I guess many tutorials are not made for absolute beginners and they have assumed you have learnt the basics before jumping into their topic. For example, if you never learn programming and set up an ide before, it has no way you can learn OpenGL as your first tutorial, and all the syntax and commands will look alienated.

And you can't write every document with an assumption that the reader knows nothing. Each document would end up the size of a phone book if you explained every single piece of technology used and provided tutorials for them.

Knowing where to jump in your stack is a tricky question, though.

OpenGL is not so bad because the API is quite stable. WebGL in particular is great because there's literally zero setup you need to do for executing it.

Integrating with Linux/Windows display surfaces is disgusting however. KMSDRM is way, way better than the nightmare that is X11 and Wayland.

Personally, my main problem when learning new things is that, once an ecosystem has matured to a certain point, there's a baseline of knowledge that everyone inside that ecosystem has. In anything I read about it, this knowledge is assumed, and if I search for it, all the old articles that talk about it are either no longer available or just wrong, because that baseline knowledge gradually evolved as the tech matured, unnoticeably to the people inside the ecosystem.

This is an area where I find LLMs to be extremely valuable, as they often still contain that knowledge and can explain it to me in a way that makes sense.

My recent experience with getting an app deployed from Gitlab to a kubernetes cluster on DigitalOcean was exactly like this. There were like 3 or 4 different third-party technologies I was expected to set up with absolutely no explanation of what problem they're solving, and there was a bunch of steps where I had to supply names or paths as command-line arguments with no guidance on what these values should contain (is it arbitrary? Does it need to match something else?)

Mind you, I have relatively good Docker experience (wrote Dockerfiles, have a pretty extensive Docker-Compose - based home server with ~15 services) so I'm not new to containers at all. But man, the documentation for all these tools was worse than useless.

I tend to write overly-long tutorials [0]. They are usually aimed at developers that reflect my own capabilities, but about a decade ago (in experience, but not tech). I write about relatively specific, advanced topics, aimed at folks with a baseline level of understanding.

I use a lot of well-tested code samples.

Writing for true newcomers, is very difficult, as there’s a lot of context-building.

My code documentation[1], on the other hand, is written for folks at my level (I basically write documentation that I want to read).

[0] https://littlegreenviper.com/miscellany

[1] https://littlegreenviper.com/leaving-a-legacy/

What it should look like:

Have a bunch of checkboxes at the top, one for each buzzword, each technology and all other things a 12 year old wouldn't be familiar with.

You check which you think to be familiar with and all other things unfold a short description with links to similar interactive documents.

Each section comes with 1-5 star rating for how well the reader understood your explanation.

Then you gather the data as the subjects suffer though the tutorial.

If people come from specific backgrounds further tailor the explanation for them.(Like babazoofoo for C++ developers.)

Let there be a browser extension or an API that checks (and hides) the familiar boxes for you.

I didn't say it was possible to make. It would be glorious to have. If you know all the tech involved the whole thing implodes into a one line code example.

This is a nice idea, but looking back at how not only documentation, but also UX in general has not improved the slightest over the last decades, it's fair to say the only way we'll ever get close to anything like this is by leveraging personal LLM assistants, unfortunately.

So be it? An additional thought I had was that new tools can have awesome discoverability in a webdirectory of tutorials. Normally the more exotic the creature the better it hides. We could be publishing a lot of things that could be great for an audience near zero. It wouldn't even need an awesome name to point at, just the right location in the right tutorial(s).

If llms are to do it we could probably have it make videos too. I want Derek Banas on the project.

Clearly the author is not the target audience and is trying to read a text they lack the foundation for understanding.

This is very different from bad documentation or writing.

Not everything should be reduced to eli5.

> How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner

Such Jargon! What's a developer? some kind of person who takes my fujifilm and gives me photos? And why do I care if someone is not such a person. Tutorial? what is this stuff do I need to sit in a small classroom? How do I read some college students sitting bored in a classroom?

So many tutorials will just assume everybody's system, workflow, tooling, etc. are exactly the same as theirs. How many tutorials start with just "brew install"? It wouldn't take much time at all to say "You can use Homebrew to install this - here is a link to install Homebrew for macOS and Linux"

My personal favourite is when I'm trying to debug something and the suggestions all say "sudo xyz".

Thanks but if I could have used admin permissions to dig deeper I would have done so already. A lot of us can't do that on company computers.

This reminds me of the Rockwell Retro Encabulator[1]. I understand the frustration.

[1] https://www.youtube.com/watch?v=RXJKdh1KZ0w

I was thinking about the same thing. Such a classic!

I don't see why there's an expectation that a "non-developer" should be able to understand documentation or tutorials written for beginners. It's a specialized field with technical jargon. There's a reasonable expectation that the person reading your tutorial is at least marginally competent. Beginner doesn't necessarily mean "non-developer." It could as well mean "new to this stack/technique/idea." I know this was written in good fun, but the implications that you shouldn't need some baseline competence to work through a tutorial is just wrong-headed. It benefits the reader to run into roadblocks and work through them. That's how you learn.

I call it "Kindergarten speak". People at the highest level of technical expertise sometimes have it, where they can patiently, and in understandable terms, explain to the most junior (but interested) party so the stuff sticks.

Others, while extremely nice and helpful, just don't "get" that their advanced jargon or, in my workplace, advanced mathematical language/notation, however elegant for themselves, is a huge hindrance for those not as versed in the art.

So if I, personally, say someone can explain something in kindergarten speak, that's the highest compliment. The more advanced lingo/notation stuff can come later, once the explainee has the big picture.

This is obvious for us who believe in and spend time on writing good documentation, but there are a surprising amount of devs out there who don't. "The code speaks for itself" people. Never understood them (literally) it's like some cult from the middle ages.

This is how I, a web developer, feel whenever I'm required to build something using cmake. I guess I need to go read a book about it or something because the instructions seem different every time.

I've been coding in C++ since the 90s, that's also how I feel whenever I'm required to build something using cmake.

Which is funny, because it's probably the easiest to use (common) build system around.

This is hilarious to me, because for me it is exactly the other way around.

Just last Friday, some coworker showed me her mermaid diagrams about workflows at work. I am still not comfortable with needing to login to some website to convert some format into a useful format. If I cannot run it locally on my computer it doesn't exist for me. So I tried to install their official looking cli client.

The protocol from my memory roughly looks like this I npm install something, then it tells me I have to npx (wth is that? I think that is new) install something, which gives me some weird puppeteer permissions issue. If it is permissions I guess I have to be root for the install, I try a bit more and get nowhere the same issues keep happening. Look on their website, see they have a docker as an alternative, this is a pretty newly installed computer so I have to install docker, but which one? There is 3 options and I am not sure. I try to run their docker and mess up because I do not read the documentation correctly and I have to map the directory with my .mdd file with <my-dir>:/data and this was unintuitive to me so I ignored the first part and replaced /data with my path. Again obviously a mistake on my side, but it happens every time and adds to my confusion. I look into the docs again and find my mistake. I finally get a resulting svg from the docker command. Excitement! I open the svg and it lacks all the text and I think there were also errors in the shape. Then I remember obsidian has a mermaid plugin so I thought about trying that, but the obsidian install also fails with some random error about not being able to connect to chrome.

On the other hand whenever I get a cmake project I clone it. I create a folder for the build, cd into it, run cmake <path-to-source-folder> without even looking at the documentation and it either works or I get a pretty clear message what is missing on my OS and with a short web search I can just apt install it and try again (yes this sometimes has multiple rounds) and it works!

Ok, my turn now. Let's build the project 'msdfgen' using cmake.

First step is cloning the 'msdfgen' repo. Done. Next step is reading the readme, which states "to build the project from source, you may use the included CMake script. In its default configuration, it requires vcpkg as the provider for third-party library dependencies. If you set the environment variable VCPKG_ROOT to the vcpkg directory, the CMake configuration will take care of fetching all required packages from vcpkg."

Google 'vcpkg' and end up at the vcpkg website. Click 'get started'. Land on a documentation page. This doesn't look like the right place. Click back and select 'browse packages' instead. This doesn't look like the right place either. Google 'install vcpkg windows'. Find a microsft site saying I need to clone the vcpkg repo. Ok. Clone vcpkg repo. Next step is running the vcpkg bootstrap script. Cd into the directory. Run '.\bootstrap-vcpkg.bat'. Next step is setting the environment variable. Open powershell. Add vcpkg to my path environment variable by copy pasting what the website tells me. Cd back into the original repo. Google how to build using cmake. It looks like I need to install cmake by first downloading the executable from the cmake website. Download cmake 4.1.1. Install.

Ok, it's time to run cmake. Navigate to the guide on the cmake website. It looks like I need to first create a build directory alongside my source directory. Open terminal and navigate to the folder just above the msdfgen-master folder. Run mkdir msdfgen-build in powershell. It looks like I now need to cd into this folder and run 'cmake ..\msdfgen-master'. Run it. It fails with three errors. "Vcpkg triplet not explicitly specified and could not be deduced. Recommend using -A to explicitly select platform (Win32 or x64)". Google what this means. Confusing. Look at the second error "CMake Error at CMakeLists.txt:70 (project): Running 'nmake' '-?' failed with: no such file or directory". Hmm, what is 'nmake'? Google it. It looks like I might need to install 'nmake' and add it to my path environment variable as well. Google it. It looks like I need to install "Visual C++ Development Tools". Google it. It looks like I need to install Visual Studio, and choose "desktop development with c++". Total space required: 10gb. Install this. Restart powershell and cd back into the build directory. Run 'cmake ..\msdfgen-master' again. Same errors.

If I had time, I'd continue down this path, but I know from experience that it will require another day or two of tooling around to get it working. I know I probably look like an idiot who doesn't understand cmake, but that's my whole point: it's a very confusing process for anyone who's unfamiliar.

The main advantage of cmake is it's slightly easier to use than autoconf so long as you stick to the path. Do not attempt to leave the path. Also the path is poorly signposted.

That's true for the developer, but for the user Autoconf is way easier. You can pass --help and it explains every option and also has a produces detailed logs.

That is the typical experience for C++ tooling lol

C++ is written by 99% professional architecture astronauts who do fuck all in terms of valuable software. I will die on this hill.

When I started with programming I didn't have issues like this at all. Most problems that I've faced where of the kind that when you compile or build that it didn't work and you have to spend hours going down the rabbit hole of dependency hell.

When I was at the head of the jailbroken iPhone ecosystem, I put together a tutorial for how to get an SSH daemon set up on their phones. I put a lot of effort into making it something that anyone could follow, step by step, and achieve the result, making sure to skip no steps, assume no knowledge, and with screenshots showing the interface.

I soon thereafter received an e-mail from someone saying that they had excitedly followed my tutorial and found it very easy to follow; but, they had now gotten to the end of the instructions, were staring at some text that said "mobile@iPhone ~$ " (or whatever the default bash prompt was; I do not remember) and they did not know how to proceed.

I had similar experiences over the years, and I had a realization at some point: if you provide someone detailed step-by-step instructions for how to find the dragon, part of the UI/UX of the tutorial should be that you don't actually feel comfortable following it if you should not be doing so: the difficulty of the path must scale with the goal.

This is similar to real-world affordances, FWIW: if a user should not be opening a panel unless they are ready to do maintenance, yes, don't go out of your way to make it hard to service without permanently damaging it (that's evil), but, maybe, screwing the panel shut is more appropriate than providing a pull tab, due to what the latter implies.

A lot of users find this annoying, because they think they want to do X, and they just need better step-by-step instructions... but, that's just not how the world works: a lot of times, what you need to do to do the task is, in fact, a basic knowledge of the entire system, sufficient that you will need a fraction of the instructions (if any).

On the other side it causes another problem, BTW: if you make instructions that anyone can follow--including people who probably aren't at the level where they should do so yet--you also end up with instructions that are more difficult to follow for the people who should be doing so, as they are extremely verbose and often narrow in their scope.

It also sets up perverse incentives to try to make the instructions even easier to follow, well past the level of easiness the task should actually be at, which, again, causes problems for the people you actually want following the tutorial: if you find yourself creating little docker containers to avoid saying "install a compiler"... no.

FWIW, I was one of your users - back when it seemed important to jailbreak my iPhone - and I appreciate the work you put into it. I'm guessing that it was pretty thankless, for the most part.

Brilliant to see something from you here - a long time ago, I was there as well using your products and making a mess of things with stuff like afc2add and iPhoneBrowser

Most docs I read have their prerequisites spelled out.

This is the version of this OS with this plugin that this guide is written for.

So when I find that, inevitably, something has moved, I can figure out how my setup differs and search for the difference.

If you cant stand up the prerequisites, then the doco isnt for you, you should be searching for documentation on how to stand up the prerequisites.

Funnily that's one of the first questions on my mind when I look at a new program or library. What was it written in or what platform for, what's the build system or requirements and what does it actually do. Quite often I decide to avoid a thing entirely when I can't figure this out after reading the main documents. Sometimes you can look at the repo tree and just know, but often not.

This should be the first sentence in the landing page or README IMO. Instead you get something that looks like marketing copy written by LLM fed on BS generator output. Many projects just seem to refuse to tell the prerequisites at all.

This article begs a more important question, is the burden of understanding the article / tutorial on the reader or is the burden of making it understandable on the writter?

I think a reasonable amount of knowledge about the topic being discussed in the tutorial should be expected from the reader but this should also be communicated by the writer.

I wonder if there's just a mismatch in what 'a beginner' means. Perhaps the tutorial is aimed at beginners _in this specific topic_ ? I have also read 'intro to x' tutorials and had to do a lot of wider reading, I just accept that's the cost of trying something outside my area of knowledge.

Tutorial is effectively a list of written orders. Problem is that if orders are not written in a detailed and specific way, person on the other side can interpret it in wildly different way.

This has been, and still is, a huge issue for military. Whole battles has been lost because order from a general was too vague or too open to interpretation (General Lee has been infamous for issuing vague orders which screw him up on Gettysburg). Prussians has invented whole wargaming which effectively has been generals writing orders in one room and officers pushing model armies in another room and reporting back to general in writing.

LLM is very good at filtering who can ask a correct question - order LLM what to do. People who can express themselves and describe problem will always get more mileage from LLM than people who will just throw vague request on it.

I am surprised nobody mentioned the curse of knowledge: https://en.wikipedia.org/wiki/Curse_of_knowledge

It is actually a fairly well known phenomenon, certainly in educational circles. Being aware of it when you are writing any form of documentation is a first step. But even then, it is very difficult to properly assess the knowledge entry level of your audience.

Having others read through your documentation and importantly work with your documentation is a good strategy.

One thing I can also highly recommend is simply start out with a list of assumed prerequisite knowledge in your intro. Specifically things like certain environments, frameworks, etc. Bonus points for not only listing those but also linking to the documentation for those.

But is this tutorial meant for a non developer to read? I would imagine a linguistic psychology tutorial would have the same effect on a dev written by an expert.

Yeah, this poor guy stumbling around the internet who should be reading kids books keeps clicking on kubernetes how-tos

Back when I was teaching myself Spring circa 2015 there was this one guy called mkyong who literally just did Spring tutorials - his site's still online at mkyong.com[0] - and while I did occasionally use Baeldung and the Spring docs, it was ultimately mkyong's tutorials that got me where I needed to be. The Internet is full of these kind of unsung heroes who happen to be really good at spelling out how to do something so simply an idiot could follow it. You kind of take them for granted as you train yourself up!

[0] https://mkyong.com/tutorials/spring-tutorials/

Code samples. This is what’s missing most of the time. Even if you encounter esoteric jargon, if they give a few examples, it’s pretty easy to decipher. Even big companies like Google give code examples in multiple languages.

Indeed, if the author had added this code sample, it all would have been clear.

    f←{⍸≠⌈\(⍴∘∪⊢∨⍳)¨⍳⍵}

---

Said in light-hearted jest, and not in sarcasm

You are a beginner for a short time. Once you get your bearings you will beg for more resources beyond a beginner tutorial.

A serious framework, language or any other tool geared towards production, has to be supported by docs, tutorials and (where possible) a community of people actually deploying this stuff, possibly at scale.

I wonder if we'll see another post next year when OP realizes there's virtually no content for the Shoobahooba Snarfus ecosystem beyond some 'get started' guides.

> You are a beginner for a short time.

If you have the right mindset and consciously seek to progress past it, yes.

I can recall seeing people spend years on concepts in a way where I really couldn't rule out the possibility of dedicated trolling. I remember one who would repeatedly ask about fixing problems with code examples using various advanced (at the time) graphics APIs while clearly missing several fundamentals about writing code in the language. And who also seemingly refused, the entire time, to adopt the proper spelling of "variable", despite it being corrected by multiple people in every discussion.

This is spot on, and can apply to anyone branching out into a new area. I will add this concrete piece of advice that can simplify things:

Don't ask the user to install tools or use ones that are not core to the topic. I still have a bad taste in my mouth from the 2 Scoops of Django tutorial after getting stuck installing VirtualBox, Chef, and Vagrant. The solution was to just not use them, because they don't have anything to do with Python, Django, or making a web server.

I don't get it. I learnt to program from tutorials in the early 2000s. I guess at some point in my education I also learnt how to look stuff up. It turns out that was the real skill all along, I guess. So the question is why do people find looking stuff up so difficult? Can you imagine how long every tutorial would be if it started from the bottom? "If you want to make an apple, you must first invent the universe."

We devs are really good at answering two out of three questions:

1. How? This is the tutorial. It might be really helpful, for specifically what is being taught.

2. What? This is the reference documentation. It's often the most usable and complete resource.

3. Why? This is the context. It can only be learned by getting familiar with the environment. This journey is where we devs grow our metaphorical (and sometimes literal) neckbeards.

---

We could stand to pay a lot more attention to question #3. The contexts we have surrounded ourselves with are messy, conflicted, incompatible, and surprising. Some particularly savvy devs have made incredibly powerful tools to help clean up this mess, yet somehow those tools are some of the least noob-friendly software we have! How did we get here? Is there any way out?

I think the most uninviting part of our environment is also the most familiar: the shell. There are a lot of pokey bits that we really don't need anymore: escape sequences, suspend, environment variables, etc. What would happen if we took a serious look at starting from scratch? Could we do better than a REPL?

It's pretty incredible that after all these years, no one has actually made a real competitive alternative to the shell, and I have a theory for how we got here. The GUI model was created by corporations for proprietary software. We call them "applications", because they are supposed to cater to a specific predetermined use case, which is precisely what makes them inferior to shell utilities. This development model isn't limited to GUI either: apps have taken over the entire development scene.

I think if we really started fresh, we could revolutionize modern software to be more compatible, flexible, and malleable than any application could ever be. That's what a shell is already, which is why we devs never want to leave it behind.

The hidden files >_<. The classic "edit config.yml" step with no idea where the file should be. Special bonus for RKE2 would used to not even mention you had to create a folder to put the config file in because their install script does not do it for you.

But a part which is not mentioned in this blurb is locality of information. A good example would be traefik documentation where every part of the doc is written like you've already read all of it. Usually with not even a link between the different parts mentioning each other so don't expect something like a table of values where an option is mentioned.

"But you should learn all of it if you want to use it". Sorry but nope. Most people using your documentation will be of 2 types:

- they want to check what your software can do and will just try to get something running fast. So you need a good "get started" and some "how-tos" showing what it can do - something is burning in production, they need a solution fast and it seems the problem is your piece of software which they don't know. You may want a guide on how to debug your thing. At least you want relevant information to be fast to get and easily googable.

These days I dump code into an LLM, ELI5. Then ask it to tell me logical chunks and overall structure. I then go from there.

> In the terminal, ajkl;gawgor;iqeg;iJLkqen. wl;R aw;oeiga 4648664 arjarwgj;llj;ja fadgfgajkljl; wlj;sdjk;lfas

Open, copy and paste, press enter

> Next go to folder/hidden/deep/in/the/file/system/surprise!.file and copy the contents of the file.

Also a primitive file operation via copy and paste of the path and file content, not even requiring 1 google search to find out how to show hidden files a complete novice would need

> Next go to folder/hidden/deep/in/the/file/system/surprise!.file and copy the contents of the file.

Same primitive copy and paste operation

> The first 3 steps will take me approximately 7 hours and 193 internet searches to complete.

Everything is possible and this isn't literal, but still that's just nonsense unless you come up with a plausible scenario where the challenge isn't copy and paste operations with no cognitive overhead

good job, you missed the point

Great job, you've failed to document the point.

The title here is beginner developer, but the article states non-developer.

Nevertheless, dev docs are usually written for reasonably experienced developers, but new to specific framework/library.

These docs would be too long-winded if they were to account for non-devs/complete beginners.

Please, don't cater to that audience in your docs.

It's people sharing with others of equivalent skill. Use an LLM to adjust to your skill level. The times I write this it's to document something that worked. There's no guarantee it's what will work for you. You're supposed to translate it. So it's not really written for you.

I followed this tutorial but ran into an issue where shamrock portal kept crashing. When I checked the logs, I found it would start a beep but never finish a boop. After a few hours of Googling I discovered my Debian 12's Klingon troglodyte emulator had a known centipede reported in 2013 that's never been squashed because hoobastank 34.100-6x00 actually requires it, and Debian can't move to the newer version of hoobastank without a major gLibc upgrade. I got shamrock talking after compiling the compatibility shim for single-threaded pintafore and migrating from Debian to Fedora 75bit, but then the fistifunk socket closed! A few more hours troubleshooting and eventually figured out the root cause: The Snarfus node's DNS resolver was down. Turned it back on and everything worked perfectly.

It's easy to blame Hoobastank, but in my experience with these issues, most of the time the reason is you.

Perfect HN comment parody and music reference at the same time.

Not emulator, emulater. This technical term may also hyphenated, emu-later.

Emu-laterrrrrr… and Doug.

I would bemoan the effectiveness of the advertising on me, but it’s just nice to see somewhat traditional advertisement styles working in the age of 5 second ads.

Wait really?? I also wound up migrating to Fedora 75bit for basically the same reason (TopHat doesn't even support hoobastank). But then I couldn't find `file` in the specified directory. I have

`library/Lib/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam/file` and `/hahahahereiam/file.`, but neither of these boop.

Any help would be greatly appreciated.

It was moved to a new path so you have to create symlinks in both locations to the new path under /usr/lib/newlib1.2/newfile.so otherwise, You can download a script that will make that for you but it will only work if you have all the dependencies for that script installed and their version numbers match the ones that the script owner had when he wrote the script.

So sorry about that. I should have mentioned the DNS resolver as a potential issue because it’s always DNS. Terrible oversight on my part, probably because I am not a developer.

Oh please, this is why it's _clearly_ superior to run Catenary or P. Papua

Right now I am a tech writer and the curse of knowledge is hard to break for many people. I've gotten a lot of docs from devs that are obviously just reminders for themselves of what they already know. I've had to flesh out docs that just stop halfway through a procedure.

Please just admit that writing docs is hard. Because it is. Just because there is a lot of writing going on in college doesn't mean you learn how to do technical writing, academic writing is very different.

Go to the support team and ask them what questions are they sick to death of having to deal with (hint: its usually something you would think is pretty easy) and rewrite the doc to handle it. Then watch what happens to the support questions, if that disappears you did it right.

As a developer, this is how I feel when I open a higher math textbook. Even though I understand that, in principle, mathematicians are using a syntax and lingo that shares some common features with computer code, my eyes slide over the words and symbols like they’re a foreign language.

But you are starting at a level that assumes you are no longer a math beginner but rather a beginner in this particular area. If you were reading a high school algebra textbook, you shouldn’t have the same issue.

It's not just programming tutorials, but it's a phenomenon that is widespread [1].

[1] https://en.wikipedia.org/wiki/Curse_of_knowledge

On the flip side, it's taken me a long time to break my skimming habits and read slowly when I'm a novice in a new area. Especially with math or software engineering, it's often necessary to stop at each word I don't understand, unpack it, and gradually build a scaffolding for myself. This is very slow, but it pays dividends extremely quickly.

As a rule of thumb, it seems like skimming is useful if one already have a good familiarity with a subject and the content is slotting into an existing mental framework. However, when that's not the case, skimming gives me the feeling that I've learned something without much real progress.

One of my first policies: Every time we have a new hire, the first thing we do is have them go through our onboarding documentation and ask them to make corrections, improvements, and add clarifying notes.

It's their first contribution to our code base.

This has been a very informative and entertaining evening for me. I loved reading the comments. Also thanks for all the guestbook posts, they bring me great joy. May your Snarfus boop correctly forevermore. Devs are great.

—Annie, not a dev

I could say the same thing about me "non-legal person" trying to read any contract, terms of service or a license document. Many people tend to make fun of the developers speaking a different language, without realizing, that they do the same in their respective field. I think clear communication is important, but you can't expect anybody to write tutorials aimed for every audience. Learning is hard and it takes time to navigate through all the buzzwords and terms, but that's what learning something new requires.

I wrote about this a while back [1] because most documentation is just plain bad. At best it's a reiteration of what is obvious and at worst it doesn't exist. Far too often it says too little of the bigger picture and too much of oddly specific edge case details. If I can't come to your project from 0 knowledge about your project and get it running without tearing my hair out, the docs failed.

[1] https://mc-deltat.github.io/articles/what-the-f-is-this-code...

Sounds like you may not be ready to read this tutorial just yet. Maybe get more experience in the terminal, and read docs on specific languages (elixir has good ones, for instance) or take a hands-on course (like Codecademy Javascript, etc).

Then, once you have more experience, you can go back to that tutorial and try reading it with more polished eyes.

What you've posted is the equivalent of me taking a new interest in cooking but applying to culinary school. If I haven't cooked in a real (production, high volume) kitchen, it's all gonna be Greek, overwhelming, and turn me off.

That was a good bit of humor.

Also there are some popular ways of explaining things that don't do the job (your experience is maybe different). For example: try to learn very basics of object oriented programming. The tutorial will inevitably have examples like "Class Bicycle" or "Class Car". These are out of programming context and never helped me to understand how to benefit from OOP in programming.

Another example is git tutorials. Having used git for years it feels so simple. In the very beginning it wasn't and those maps with circles and arrows didn't help.

Class Car isn't a bad place to start. It's a real example and something you will find in professional game engines:

https://dev.epicgames.com/documentation/en-us/unreal-engine/...

A lot of kids who learn programming are motivated by a desire to make video games, and everyone already knows what a car is, so such class hierarchies are a good way to teach the concept.

On HN it's trendy to bash OOP and inheritance but it's a bubble; contempt born of familiarity. Real world codebases all use it extensively, including new codebases, and they use it because it's often a reasonable point in the design space for modeling problems. It's not perfect but the alternatives all have major issues of their own.

Obviously once a budding developer realizes that he can't find a job writing game engines and 'graduates' to writing DB driven web apps, the objects and class hierarchies he finds will be representing much more abstract concepts. But by then he'll understand what those concepts are, having mastered them in a less abstract concept space.

This hits home, and not even relegated to software. My partner decided to learn to ride a motorcycle during the pandemic. I’ve been riding in some form or another for more than half my life. In the first minutes of attempting to explain the procedures, I immediately realized there were years of involuntary movements and coordination I failed to articulate because it wasn’t a part of my mental model of the process.

Needless to say she signed up for a professional course, got the license, and we’ve travelled nearly 10,000 miles together since!

"beginner". Docs are written this was are targeted at other developers who are experienced. You know this by the fact your calling yourself beginner and this isn't a friendly coding camp where everyone is making a robotic arm go up and down in python. This is being a real world developer.

To a "non-developer", yes that's what being in _this_ industry is like/about. If like taking a random coder and expecting them to read instructions to make something using crochet. There's a learning curve...

We did something similar with 'prod' code reviews. We started including a couple of the more junior folks in a pre-release review that was mandated. Intent was to say fine, id tech debt, or pull the andon cord if something was missed that would impact prod. What came out of it were their questions - which almost always was translated into an ask for documentation for that bit of code. The secondary bonus was they learned the questions that would be asked of the people who were merging.

How I, a professional developer of 15 years, read the prose-heavy README you, a developer, wrote on your repo.

All docs should start with examples. Some docs would be better if they ended right there.

This is very funny, but developers usually aren't writing development tutorials for "non-developers."

Even the submitter must have realized this, which is why they changed the title.

Why be so snarky? Documentation is there for users, it should assume that the user has the necessary background. If the user doesn't it is his responsibility to read up on the relevant background.

Pushing the burden of education on every single developer writing a tutorial is absurd. It makes the documentation unreadable to the people who need it the most and wastes time and effort. This style of documentation is totally fine.

Education is your own responsibility, do not push it on others.

This level of extreme hyperbole is silly and not in any way helpful. Try analyzing an actual tutorial (which will only be an analysis of that one--quality varies a lot).

That was the analysis of an actual tutorial.

Good observation. Silly is the point. You nailed it.

I’m not doing this either but: ideally tutorials should work on a very well defined environment (clean install, VPS with X setting, application deploy at version X with plugins at versions A, B, C)

Then they should have a unit test. And a passing status. The problem with most tutorials is that they simply rot. So many times they tell you to do a command with a flag that doesn’t exist, install two incompatible packages or click a button that isn’t there.

Yeah...

I usually go over my guides and tutorials and try to remove jargon when possible.

However, I also try to clearify the target audience.

When I write a tutorial about storing files on S3 with the AWS SDK for Node.js, I won't start by explaining what JavaScript is.

Still, if I write something that has a reasonable chance that it is read by many programming beginners, I tend to add a link to FreeCodeCamp courses that help the readers to get the minimal education to follow my piece.

Unfortunately, the curse continues: follow up with how the text gradually coalesces as understanding grows. Realize how much easier it is after completion. Forget what "don't know what one doesn't know" felt like.

At least the beginner perspective captured enthusiasm, empathy (an alternative error condition for a path to a hidden file), and the request for feedback.

I'm a developer and I read most tutorials like this.

Pretty much every "thing" I come across today uses some kind of dependency that I have little, or no, experience with. Unfortunately, even though the "thing" might be interesting, the fact that I'll have to spend 4-16 hours futzing with things that are completely new to me to get somewhere is often what turns me away.

This article doesn't hit any nail on it's head. Tutorials and instructions of software are of the best quality they have ever been.

One minor tip that I think can have a big impact: whenever writing down something to run on the command line (e.g. for documentation or other kind of sharing), always use the --full-version of the flags (instead of the short -f version). The extra information it conveys is worth a lot. If someone gets tired of typing it, it's easy to find the short version.

The real title was, How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner

The edited title does not have the same meaning. Why was the done? How often is this being done? What else is being changed?

If I write a title on my blog saying, I like Java, what is to prevent you from changing it to I hate puppies.

It's always a problem that you forget what you use to not know.

When I first started writing some internal docs/tutorials at work, I was new to Linux. So I generally took the time to include tangents into explaining fairly basic Linux concepts, because they were new to me. They were rough edges I had to get past so I wanted to help others do the same.

Five years and a shit load of Linux experience later, I don't do that anymore. That stuff has become so second nature to me that it just doesn't even occur to me anymore. And I just don't have the damn time. If I had to stop to explain what cat or sudo or | mean in every doc I write I wouldn't have time to get anything done.

> Just for shits and giggles, you can de-sham the chronostatiomatrix by running —()()(]]asdg a=-do —cd go cd stay —sususudododo baby shark—][] but that’s optional.

Except in most real cases you're following the tutorial for, where it is both mandatory and non-obvious it's not been done.

Something like the mock one here I think is really more often largely intended as a sort of logbook entry, a note to self, 'how I did x' (in case it breaks, I need to do it again, update it), it isn't really 'for me', the other.

You could replace specialized terms with nonsense words in anything. This is completely non-actionable critique.

In the end, there is no Royal Road to learning. You have to create put in the effort to create new concepts in your head to understand something.

If you can't understand half the words, you're not the target audience, period.

150 replies, and not a single mention of MCP servers? I feel like more and more tutorials are being replaced with MCP servers and expecting the user to type "connect lib pls" into their AI chat box.

This is such a good point. I've changed jobs a lot and one thing consistently bad (to varying degrees) is documentation and tutorials specifically.

"Download X and setup"

"It's not working..."

"Oh yeah, you're supposed to do it on the remote access VM"

"It says access denied"

"Oh right, you're supposed to use the Yubikey for access"

"I don't have a Yubikey, its pass + authenticator"

"Ok, I'll email Jeff from this department you wont hear off until someone new starts. But otherwise keep following the tutorial and you should be good to go!"

It always infuriates me. At my last job I had a lot more control and authority, so I redid the entire tutorial for the proj we worked on. Every few months I'd check all my account permissions, update the list on the readme, spin up Windows/Ubuntu VMs and try to get the project running using ONLY the tutorial. Anything missing - add it.

If anyone added a new dependency the documentation would be updated and the steps checked on a new VM. I did this as we had various people come in and work for a few weeks, add a new feature and leave. The end result was that instead of 1-2 weeks to get running, people would have everything running within their first day and start work sooner. Instead of needing someone for 4 weeks for ONE feature, we could finish 2-3 and sprinkle in more tests and confidence.

I think most developers would benefit from writing for a less experienced audience, especially for this sort of thing.

I've always this attitude that the one after me should not face the same issues as I had and so I update all wrong documentation, this also helps me remember how stuff works. But I have had many occasions where I just had to give up. People thought I was being annoying, my PR for fixed Readme (or even a Readme at all at times!) were simply not picked up, etc, etc.

I left that company, and left a letter for management about the abysmal developer experience.

The funniest part, lol

    it might be in library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam.file.

On Fedora you'll find it in: library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam.file.d/boop_settings.cfg

I went to library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope but I don't seem to have a /never/ folder at all.

    bash: cd: too many arguments

   sususudododo baby shark

...looks scary as well in hands of inexperienced.

If anyone has an open source project and wants a review of their README and docs, please get in touch. I enjoy providing this type of feedback, and I think every project can benefit from it.

I once was asked to teach a class in beginning C++ that was put in the paper as beginning programming in C++. Some of the students really weren’t ready for the class they found themselves in.

But is it a tutorial, if it's as described? Or someone's hasty notes?

Is that format better or worse than the SEO tutorials that spend half the time explaining what a conditional statement or a loop is?

i started frequenting hackernews because i knew that tutorials written by developers would start making sense if i just kept trying to read them. it worked!! took a few years though.

I have not laughed this hard in front of my computer in a long time. What a gem. (as a non-developer also, this experience really hit home)

Honorable mention: https://youtu.be/aW2LvQUcwqc?si=IqPtgd3cxpUKwWRm

Makes me want to revisit my (started, but not posted) screenshots and videos of trying to install matrix / element following the random directions / docs.

This mirrors my experiences 20 years go, but I actually appreciated it because it pushed me harder to learn the dev arcane languages.

every publication has a target audience.

A paper in a cancer journal and a Web MD blog can discuss the same disease, and both will seem like a foreign language to the wrong audience.

And now we have LLMs, most of the "trade words" and jargon can easily be translated into a kindergarten reading level if that's the reader's background.

Honestly, I'd say this doesn't even just apply to beginners to software development. It's applicable to even experienced developers who are new to a language or concept.

I've been teaching myself Rust in the past week and I've definitely noticed that, when I hit an error, a lot of library documentation assumes more depth of knowledge than I have right now. Say I want to know how to use a specific function and, beyond the quickstart, the docs are just a reference that keeps talking about Traits. I'm sure it'll click eventually, but right now, I just need to know how to call the function and fix the error I have!

Side note: I've rediscovered why Stack Overflow is so helpful as some of the answers there have helped me understand what's happening with different issues I run into!

Next time I won't forget to improve my life by running sususudododo baby shark on a regular basis.

OPs argument is flawed. Documentation is not there to teach you from scratch. Its there to describe a projects intended behaviour under normal conditions. Often times people will cry about lacking context and expect you to basically use it for them. I would heavily recommend against that as you will end up as unpayed and burned out tech support...

OPs everything is flawed but she tries really hard.

If this is you trying really hard ...

nice alt

Thanks for this. I never knew how much I'd like it if George Saunders started a tech blog.

Omg this is high praise I’ll never be able to write anything again

This is how I feel trying to follow tutorials for using LLM or GenAI (LoRA, agentic, MCP what?)

Developers assuming way too much, in depth and in detail, is how you know they are a developer.

James Joyce would be proud of you, my friend. Great reading. Ditto the sentiments. Congrats!

"Gee Rick, uh, I d-d-don't know if this tutorial is for real, I mean there's a bunch of random nonsense words and other stuff. I mean, is 'backside Snarfus stagnator' even a real thing?"

"Shut up Morty, you just don't unders-*buuurp*-tand what it takes to be a software engineer."

"Are you sure? What's a 'hoob-tunnel' and how does it get clogged with 'gramelions?' That just sounds like an improvised line from that sci-fi cartoon show..."

I almost had a stroke trying to read this, now I get it. Thanks for the eye-opener.

False.

Nobody writes for beginners.

Beginners who hope to be Enders know this and so grok the whatits before whinging.

Ironic that 5 years from now we will yearn for the era of human-written tutorials.

You are right but the fact that it will be harder to distinguish between human written and AI written text means that we will be looking for signs that indicate a human written text and will tend to prefer humanly mistakes over AI perfect tutorial.

So basically, it is what you should be doing with users of your apps too

Yes. Before whining do your homework and learn about the concepts.

The title is misleading. Here is the actual title:

    "How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner"

So, she is not a beginner developer, but a beginner at using your software.

Thank God Snarfus is there, a reliable tool we use for years!

As a not-a-coder, this still rings true in way to many ways.

Whenever my team (cybersecurity) is about to send a global email or post, I wander around non technical teams to get 3 or 4 people to read it and explain me what it means.

Not once I got it right on first attempt. The final version was very different from the first one.

This is similar to the web page that was proposed to serve as the message people would read in case of a critical disaster of our systems.

The first version was with Vue, Tailwindcss and whatnot and I opened it on an old phone. Everything was everywhere, with drawers all over the place. I said that I would not approve anything beyond https://motherfuckingwebsite.com/ because I need it to work on a tomagoshi.

The version we have now is beautiful in its ugliness and clarity. It opens on a smart watch (well I don't know that actually :))

Are tutorials like this even relevant nowadays with LLMs? I think articles of the future should be purely about approach, strategy and pitfalls, not "type in command x" handholding.

I am not sure if you thought through the implications of your proposal. LLMs are trained on examples in the training material. If something is new and isn't accessible because it lacks tangible examples the adoption rate will be lower, so there will be less training material and therefore LLMs will not be of use here.

In fact, that entire aspect of LLMs is something that is not talked about as often. But is worth a whole discussion in itself. If I remember correctly, the availability of training material for a technology already has slightly impacted more niche corners of the tech world.

How do you think the LLMs train?

If I release a new library tomorrow, do I not need to write docs for it?

I couldn't even understand what u had writter

There not designed for beginners, but for peers.

Nice how the blog is actually deved with ruby.

Straight from "A Clockwork Orange".

Some tutorials require previous knowledge.

If you don't understand what is written, it's clearly not written for _you_. Same reason why whitepapers are not used as textbooks in high schools.

Most devs write docs like aliens. Time to send them back to elementary school English class.

Most docs I read aren't written for an audience of non-developers.

Most docs I read aren’t written for any audience, imho.

That doesn't really excuse the strange acerbic brevity [that] I and most of my peers default to when writing technical documentation.

Jesus Christ. What kind of IDIOT tries to argyle the pintafore using hoobastank? Some "developer" this person is...

I literally said in the title I am not a developer but you’re right I should have known

Thank goodness it’s not just me. Had been assuming I was uniquely thick.

Skill issue.

This is gold

Pretty low effort as blog posts go.

Apparently it was so much more effort than she was willing to expend that she ended up just randomly banging on the keyboard ... and yet many here are treating this as some sort of serious criticism.

Accurate

I mean, if it reads like that, if probably wasn't meant for you. Which is fine, internet has a lot of content for the most obscure niches

> sususudododo baby shark

Uh oh. I'm not sure if I'm going to be able to use `sudo` anymore.

The title of the blog post currently is:

> How I, a non-developer, read the tutorial you, a developer, wrote for me

The HN title is:

> How I, a beginner developer, read the tutorial you, a developer, wrote for me

Those are different things. A "non-developer" reads as someone who isn't supposed to understand any of this. I am imagining a human resource person, a customer completely unfamiliar with internals, someone from a completely different area of expertise. They shouldn't have to know what snarfus are, or how to fisterfunk the shamrock portal. In that case yes, let's mock the developer for completely missing the mark with a 6 paragraph long joke.

A beginner developer, however, is someone completely different. This is a person who will eventually have to juggle snarfus, and as unfortunate as it may be, even need to fisterfunk the shamrock portal. It is partially on them to put some effort into figuring out what fisterfunking is, and how it applies to the portal. If they are particularly good, after figuring out what those things are, they may even volunteer to update the documentation as to make it easier for the next beginner developer to understand it instead of replying with a 6 paragraph long joke about it.

FWIW, I submitted it as "non-developer" but a moderator seems to have changed it to "beginner developer."

The author is a non-technical blogger, and she probably has to navigate lots of technical guides in order to fiddle with her website or CSS. I think a more relevant discussion would be about making website publishing easier for everyday people, or about the lack of documentation written for that particular demographic. But HN took it in a different direction, which is fine.

This is an important clarification.

Checking out the homepage, Annie says her job is "content & documentation things", but also mentions CSS as a hobby, so I think it's a safe assumption this is the "non-professional hobby developer" niche which I think we'll see continue to grow.

It's a hard balance to get right. I've seen "install this tool" sort of tutorials which literally introduce the concept of opening a terminal and pressing Cmd+V and others which expect cron and Make knowledge as very basic table stakes. It's a wide variety!

I think if we're writing for an audience which will contain some amount of beginners or non-developers, it's maybe ~2min of effort to add a little collapsable (straight from Claude if you want) going into what exactly we mean by "cd into ~/.snarfus, creating it if it doesn't exist"

I donno. I remember being 13 trying to install Debian on my dad's old laptop. Any nuggets of knowledge helped.

The site that got me into programming as a teenager was called "FromZero" and explained how to write programs in C for non-developpers. From installing the IDE, to how to open the console, it carefully explained each step, sometimes saying "don't worry about Snarfus, we'll get into that later". It was amazing, and I owe this website my career.

That being said, I agree writing doc is time consuming and it might not be your priority, in this case partial docs is better than no docs at all. But if your target is beginner developpers, imo you should consider them as non-developpers, as you correctly descibed them.

It says "me, a beginner"

The hn submitter presumably edited for length

That changes everything

It would be crazy for a beginner developer to expect a technical post made for other developers to dive into explanations of What's Hoobijag/jabbernocks/ABCDE++++/Shoobababoo/a shamrock portal.

We've all been through that phase where you have to google the words you don't know.

For me the issue is some people expect everything to be simple/easy to do without any prior knowledge and then claiming it is not really hard but you are gatekeeping and only if you could explain it easier they would definitely grasp it instantly.

Also, it really depends on what the tutorial is about.

There's a difference between a tutorial on how to set up a wordpress on a shared hosting or how to add aditional debugging capability to kernel application core switching routines by patching the linux kernel.

In the first example, "unzip it" might need an additional explanation on how to do it in the command line... in the second,.. well... if you can't even unzip a file without the tutorial, you won't be able to use the software anyway.

In the end, lots of people who try to accomplish their goals writing some code don't see themselves as beginner developers but non-developers.

They just want to accomplish some well-defined and scoped task that happens to require some coding, but they have no interest, at least for now, on becoming developers.

oh come on please it's easy just /etc/init.apt-get/frob-set-conf --arc=0 - +/lib/syn.${SETDCONPATH}.so.4.2 even my grandma can do that

You forgot the “welcome to Linux!”

Reminds me of an acronym that defines this sort of behaviour: COIK.

What is COIK? well everyone knows what COIK is, no need to bother explaining.

COIK is 'Clear Only If Known.' Did you really have to ask me about such a simple thing? Now run along.

____

There is so much assumed knowledge that writing guides becomes a matter of how simple you have to go, before you start insulting the reader's intelligence. (A computer is a magic box that goes DING!)

If you writing a guide, do you explain what a terminal is and where to find it? Or do you presume they know what it is and start sharing command lines? Is setting a minimum knowledge bar acceptable or are you showing your bias?

____

Obligatory XKCD:

https://xkcd.com/2501/

Just confirming, I've seen that the title between the post and link are inconsistent incase there's any confusion.

While I agree, the difference is significant, and it is often the case that a a decent tutorial/blog post on a technology is rarely tailored to non developers

I do think there's a kernel of truth in this for with educational content written by developers. I think many developers underestimate the attention and care that's necessary to write high quality education material. Not to say they shouldn't, it's a valuable skill for everyone to develop but it doesn't always come naturally.

I think one part of it is, in writing the content sometimes someone who is inexperienced in writing, might be writing something with dual roles in mind. They may be venting their frustrations with learning the technology, selling their experience and accomplishments (to any potential employers who may be reading it, which is where some name dropping might be coming in) and using the format of a tutorial as a vehicle to do so. They may also just not have a clear objective of what they want to write in mind and they just want to share some information and they initially wrote a tutorial and veered off on to something else.

If you're someone who is reading something like this, it can actually be annoying or confusing if you went into the tutorial expecting one thing which doesn't end up being there. For a beginner even more so, as you lack the domain knowledge to know if you need to disregard these tangents or skip forward, if you're more experience it feel like someone is wasting your time by telling you they were going to explain X Y Z then it ends up being some rant passing as a half baked tutorial. That said I rather this than AI slop, but reading it can be equally annoying if it feels like the author doesn't respect your time in the way AI slop feels like there's an expectation your time reading it is worth less than the time the author would spent writing it.

The issue here for the reader is usually the content is inconsistent with their expectations, and for the author they possible communicated that poorly.

Yes if the author has mistakenly assumed an article not written for them were written for them, well yes that's on the author. But taking what they say at face value or even the title used at the post I think there is a point of value to take away from this for those writing anything ranging from education material to a post mortem.

Know your objective, the key information your communicating, has the way you've written effectively communicated that to your intended audience? Cull things that detract from this. And of course there's nothing wrong with unstructured forms of writing, they can be really fun, but they are the last thing someone wants to read when they are in the middle of trying to fix a technical issue they don't entirely understand. That can largely be avoided by with a better title, or avoiding insinuating the post is something it's not.

Reply on news.ycombinator.com