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.
How I, a non-developer, read the tutorial you, a developer, wrote for me
81–90 of 455 posts
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#82Most 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 w…
> 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.
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.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#83Can'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 user…
Basically, ergonomic testing, but for your doc instead of your software.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#84Can'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 user…
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.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#85Can'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 user…
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,…
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.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#86Can'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 user…
Thoroughly agree. Where I come from it's called "shoulder surfing". It is really important to not help.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#87The 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 f…
It says "me, a beginner"
The hn submitter presumably edited for length
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#88Can'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 user…
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.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#89Earlier quoted context omitted.
> 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.
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.
I fully disagree with Java as a starting point and it was an interesting conversation with the teacher.
Apparently, "College Prep" courses more or less determine that Java is the language that they should use.
His teacher thought it was stupid as well, but sometimes your hands are tied. That's what the schools are using as a starting metric though.
He was apparently the only person in the class that said he wanted to do software engineering. Don't worry, he'll be a polyglot before he reaches college.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#90This 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).