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

181–190 of 455 posts

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

#181

Post by aDyslecticCrow »

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…

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

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

#182

Post by gchamonlive »

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…

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.

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

#183

Post by ptx »

jen729w wrote: post #125
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.

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

You could probably fix this, to some extent, by adding a sidebar to the instructions that 1) acknowledges that the procedure doesn't seem to make any sense, and 2) points out why the seemingly obvious fixes won't work. That's usually immensely helpful to me as a reader, so I don't have to waste time wondering if I misunderstood the instructions or the author misunderstood the procedure.

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

#184

Post by aDyslecticCrow »

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…

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

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

#185

Post by throwaway2037 »

IanCal wrote: post #107
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…

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?").

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

#186

Post by throwaway2037 »

jen729w wrote: post #125
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.

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

Joel Spolsky famously wrote in the year 2000:

    > Users don’t have the manual, and if they did, they wouldn’t read it.

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

#187

Post by throwaway2037 »

skydhash wrote: post #180
maxloh wrote: post #138

Earlier quoted context omitted.

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

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)

About JDK Java docs:

    > Those are references, not tutorial.
This is a great phrase. I fully agree with your sentiment. To me, I never read Javadocs in HTML-only form. I always read them in an IDE, along with the library code in question. If anything is unclear from the Javadoc, then read the code (which immediately follows the Javadoc).

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

#188

Post by Schiendelman »

ocimbote wrote: post #88
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…

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…

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.

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

#189

Post by skydhash »

sebstefan wrote: post #142
rdtsc wrote: post #70

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

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.

Also a lot of beginners skipped a lot of (cultural?) foundational knowledge. A basic understanding of filesystem, network, and os commands would go a long way for communication efficiency. Instead, they’re cargo-culting.

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

#190

Post by efitz »

aDyslecticCrow wrote: post #181
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…

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

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