[deleted]
How I, a non-developer, read the tutorial you, a developer, wrote for me
91–100 of 455 posts
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#92> 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?
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#93Can'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…
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.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#94Earlier 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.
> 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 se…
Not going to disagree. It's the sandbox that we're playing in though (dealing with, HOORAY JAVA!) since it's a class at school.
Have to start somewhere, teach them better alternatives as they evolve. Not even going to broach the prototype-based programing stuff until he comfortably has the basics understood.
Edit: I don't GAF about downvotes, but I would at least expect a response about why. If you don't like the philosophy, give me some reasons. Don't like something else, tell me why. I'll happily debate anyone all day long
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#95Ironic that 5 years from now we will yearn for the era of human-written tutorials.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#96I couldn't even understand what u had writter
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#97Personally, 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.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#98Can'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,…
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"...
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#99The 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
[deleted]
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#100Can'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 (tru…
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.