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

61–70 of 455 posts

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

#61

Post by Our_Benefactors »

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…

Fully agree. Good docs are essential for scaling a team beyond the first few hires. I always make a point of filling in all the gaps I had to gather myself during my onboarding, and ask the next hire to do the same (and carry it to the next hire, and the next) this helps keep the docs up to date with the relevant knowledge since it’s always being filtered through the lens of a brand new computer and a dev with minimal context.

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

#62

Post by beeflet »

Swizec wrote: post #60
lukan wrote: post #36

Earlier quoted context omitted.

"Most tutorials are not for non-developers" That has been repeated in the comments many times now, but the very headline says that this tutorial was indeed also intended for non developers. Like some open source Github project that the author merely wanted to install, not starting to mess with the code. Basically, it is complaining in a satirical way about installation readmes, that maybe they could be made easier, t…

> it is complaining in a satirical way about installation readmes, that maybe they could be made easier, that also non developers can follow some simple steps See I missed that context :D Installation readmes are an interesting example – they shouldn’t exist. Put that effort in an install script instead. If you want me to mechanically follow some steps, perhaps with a decision tree attached … computers are really goo…

The install script may not have all the context it needs to be installed. In the long run it is better to teach the user how your software works in plain english.

Even in projects with an install script, for example pmbootstrap, the install script also needs a tutorial.

In my experience, projects with minimal documentation and an install script will have the the install script fail halfway through because it assumed something about my system that isn't true, or it will do something incredibly insecure like requesting su and then curl | bash

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

#63

Post by ChrisMarshallNY »

I tend to write overly-long tutorials [0]. They are usually aimed at developers that reflect my own capabilities, but about a decade ago (in experience, but not tech). I write about relatively specific, advanced topics, aimed at folks with a baseline level of understanding.

I use a lot of well-tested code samples.

Writing for true newcomers, is very difficult, as there’s a lot of context-building.

My code documentation[1], on the other hand, is written for folks at my level (I basically write documentation that I want to read).

[0] https://littlegreenviper.com/miscellany

[1] https://littlegreenviper.com/leaving-a-legacy/

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

#64

Post by fragmede »

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…

Totally. Something that I see a lot is software that tries to read a config file during startup that bails out (sometimes with no error message!) if the file doesn't exist. Or tries to write the config file into a directory that doesn't already exist.

I'll get things working locally first, but I always have to test it in docker/other fresh test env (Vagrant), just to be sure I haven't committed the same sin myself.

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

#66

Post by effakcuL »

maplethorpe wrote: post #13

This is how I, a web developer, feel whenever I'm required to build something using cmake. I guess I need to go read a book about it or something because the instructions seem different every time.

This is hilarious to me, because for me it is exactly the other way around.

Just last Friday, some coworker showed me her mermaid diagrams about workflows at work. I am still not comfortable with needing to login to some website to convert some format into a useful format. If I cannot run it locally on my computer it doesn't exist for me. So I tried to install their official looking cli client.

The protocol from my memory roughly looks like this I npm install something, then it tells me I have to npx (wth is that? I think that is new) install something, which gives me some weird puppeteer permissions issue. If it is permissions I guess I have to be root for the install, I try a bit more and get nowhere the same issues keep happening. Look on their website, see they have a docker as an alternative, this is a pretty newly installed computer so I have to install docker, but which one? There is 3 options and I am not sure. I try to run their docker and mess up because I do not read the documentation correctly and I have to map the directory with my .mdd file with :/data and this was unintuitive to me so I ignored the first part and replaced /data with my path. Again obviously a mistake on my side, but it happens every time and adds to my confusion. I look into the docs again and find my mistake. I finally get a resulting svg from the docker command. Excitement! I open the svg and it lacks all the text and I think there were also errors in the shape. Then I remember obsidian has a mermaid plugin so I thought about trying that, but the obsidian install also fails with some random error about not being able to connect to chrome.

On the other hand whenever I get a cmake project I clone it. I create a folder for the build, cd into it, run cmake without even looking at the documentation and it either works or I get a pretty clear message what is missing on my OS and with a short web search I can just apt install it and try again (yes this sometimes has multiple rounds) and it works!

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

#68

Post by toyg »

chickenzzzzu wrote: post #23
01HNNWZ0MV43FF wrote: post #18

Earlier quoted context omitted.

That is the typical experience for C++ tooling lol

C++ is written by 99% professional architecture astronauts who do fuck all in terms of valuable software. I will die on this hill.

C++ might have been developed by architecture astronauts, but it's used to build a ton of valuable software - KDE, Windows, Spotify, etc etc...

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

#69

Post by gertlex »

peteforde wrote: post #45

I find that a lot of project homepages (or GitHub README.md these days) are riding high on "if you're reading this, you already know what this is for" energy. What I would give for people to approach documentation in a more empathetic way; tell me what something is for, what problem it solves vs other competing solutions such as X or Y, whether it's still the best solution or in maintenance mode because another tool…

This issue with READMEs in particular has driven me nuts for the decade I've been doing ROS related robotics stuff. So many repos where the only surface clue (i.e. before diving into the code) of what it does is your interpretation of its name.

But I'm pretty sure it's universal, like you allude to. And not just open-source; but at work, too. I feel like I'm the only one in my company that makes PRs to edit the READMEs to explain what a repo is for, and what repos it might relate to. (I was much happier in the past when we had a couple mono-repos; now the trend is every little project gets its own undocumented repo, alas.)

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

#70

Post by rdtsc »

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 from a completely different area of expertise. They shouldn't have to know what snarfus are, or how to fisterfunk the shamrock portal. In that case yes, let's mock the developer for completely missing the mark with a 6 paragraph long joke.

A beginner developer, however, is someone completely different. This is a person who will eventually have to juggle snarfus, and as unfortunate as it may be, even need to fisterfunk the shamrock portal. It is partially on them to put some effort into figuring out what fisterfunking is, and how it applies to the portal. If they are particularly good, after figuring out what those things are, they may even volunteer to update the documentation as to make it easier for the next beginner developer to understand it instead of replying with a 6 paragraph long joke about it.

Post reply on HN