Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

anniemueller.com

Post reply on HN
Print view View original

231–240 of 455 posts

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

#231

Post by mgkimsal »

throwaway2037 wrote: post #185
IanCal wrote: post #107

Earlier quoted context omitted.

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…

I had this issue during a job interview exercise. Their "follow these steps exactly" were simply broken. The root cause was that they were having people re-use the same shared remote amazon desktop system. Each candidate got their own home directory, but they wouldn't just reset the image between candidates. The person before me had used up 98% of the drive space. When I followed the 'step by step' guide, nothing worked, because it was out of drive space, but... I wasn't seeing 'out of drive space' messages directly - I was seeing their 'setup shell scripts' looking like they worked, but then nothing did.

I honestly thought this was some sort of trick exercise to see how I deal with broken processes, and I was writing fixes to their docs and shell scripts to deal with error states, and reported back to the person. I initially got a 'no, this isn't that sort of test. the docs work, just follow them'. After more back and forth, I got 'oh, I see that might be broken, yeah, just carry on'. I fixed what I could, made a couple commits back up, but was then told my commits needed more context, which I then added, and promptly never heard back from them again. Until... weeks later, HR reached out to say "we've gone with someone else". I recounted this story and got at least some semblance of feigned shock of 'that's not how any of this is supposed to go'. I'd kept some screenshots and emails, but they didn't care to go down that road.

tldr - Employers giving tests, please run through your own exercise processes now and then (or maybe even automate them with some smoke tests).

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

#232

Post by bombcar »

nomilk wrote: post #48

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 user…

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

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

#233

Post by Kneecaps07 »

beklein wrote: post #169

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 ove…

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.

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

#234

Post by SoKamil »

card_zero wrote: post #119
SoKamil wrote: post #111

Earlier quoted context omitted.

The edited one is longer. Why would you want to edit the title to make it longer?

No it isn't: How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner How I, a beginner developer, read the tutorial you, a developer, wrote for me

We are kind of both correct.

GP mentioned:

> 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

So GP cut off , a beginner ending which in turn falsified my claim of it being longer, and I didn't verify blog title.

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

#236

Post by BrandoElFollito »

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 :))

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

#237

Post by swiftcoder »

nomilk wrote: post #48

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 user…

> 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

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

#238

Post by pyjamafish »

marklubi wrote: post #43
Swizec wrote: post #4

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 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.

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

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

#239

Post by bob1029 »

4pkjai wrote: post #221
nomilk wrote: post #48

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 user…

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.

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

#240

Post by whstl »

wouldbecouldbe wrote: post #230
imgabe wrote: post #225

Earlier quoted context omitted.

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.

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

> with Xcode, go to fargler settings click on narg screen

I hate how this looks "accessible" to people in theory, but in reality finding those screens is more like playing a hidden object game.

Also, I hate how those things keep changing around in all kinds of software, but especially Apple. Somebody probably thinks "yeah maybe we should move the Fargler settings from the Narg to the Birp screen", and makes dozens of internet "documentation" (and sometimes their own!) obsolete.

Post reply on HN