If you can't understand half the words, you're not the target audience, period.
How I, a non-developer, read the tutorial you, a developer, wrote for me
161–170 of 455 posts
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#162The 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…
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…
Site du Zéro mentioned!
I always assumed it meant "a website for 'zeros'" as in "complete noobs"
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#163Can'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 o…
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.)
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#164There not designed for beginners, but for peers.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#165Most 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’…
Ironically, online recipes of the cookbook kind are actually much worse for meandering and irrelevant prose than programmer blogs are.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#166Code 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
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#167Honorable mention: https://youtu.be/aW2LvQUcwqc?si=IqPtgd3cxpUKwWRm
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#168The 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.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#169When 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.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#170Back 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!