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

261–270 of 455 posts

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

#261

Post by k__ »

Yeah...

I usually go over my guides and tutorials and try to remove jargon when possible.

However, I also try to clearify the target audience.

When I write a tutorial about storing files on S3 with the AWS SDK for Node.js, I won't start by explaining what JavaScript is.

Still, if I write something that has a reasonable chance that it is read by many programming beginners, I tend to add a link to FreeCodeCamp courses that help the readers to get the minimal education to follow my piece.

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

#262

Post by gwbas1c »

I'm a developer and I read most tutorials like this.

Pretty much every "thing" I come across today uses some kind of dependency that I have little, or no, experience with. Unfortunately, even though the "thing" might be interesting, the fact that I'll have to spend 4-16 hours futzing with things that are completely new to me to get somewhere is often what turns me away.

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

#263

Post by lukan »

sfn42 wrote: post #218
throwaway2037 wrote: post #197

Earlier quoted context omitted.

> I think Java is dying. There are millions of enterprise programmers around the world that use it. If it is dying, then what is replacing it in the enterprise? From my perspective, I don't see any serious competition. At the moment, I see this pattern for mega enterprise: * C++ for scientific, mathematical, financial core libraries * Java for heavyweight backend services that run on Linux * DotNET for thick clients…

Some notes: .NET can serve the same use cases as Java, it's not just for windows programming. It's actually getting really good. NodeJS does nothing better than anyone. The only things I can think of that make node worth using is electron and react native, maybe Next but I'd much rather do SSR in a real programming language personally. I would never use node as a pure backend, there's just no reason to and JS is an F…

".NET can serve the same use cases as Java, it's not just for windows programming. It's actually getting really good."

Last time I tried NET was 15 years ago, so I have no first hand knowledge anymore, but I do read regular complaints, that cross compiling to Linux(or developing there) comes still with major hurdles at times?

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

#264

Post by lptome »

sylens wrote: post #242

So many tutorials will just assume everybody's system, workflow, tooling, etc. are exactly the same as theirs. How many tutorials start with just "brew install"? It wouldn't take much time at all to say "You can use Homebrew to install this - here is a link to install Homebrew for macOS and Linux"

My personal favourite is when I'm trying to debug something and the suggestions all say "sudo xyz".

Thanks but if I could have used admin permissions to dig deeper I would have done so already. A lot of us can't do that on company computers.

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

#265

Post by ctkhn »

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…

It's crazy how bad most onboarding docs are for corporate teams. I think it's a great first look the culture and how much of a hassle the role will be. The last three teams I've joined have been brutal with how little was documented or how out of date the docs that did exist are. I've had to spend up to two weeks tracking people down to find out what access group I need for our logs, deploy pipeline, etc. and I end up writing up a new doc that's good for its point in time, immediately becomes out of date when someone adds a new system or access group but doesn't document it anywhere. The one team I was on previously that got me everything I needed in about two days was great, but it's sad that this isn't the norm. Everywhere else has been pretty hostile to getting set up, and the poor onboarding experience has been a preview of the developer experience. My current role is standing up a new devex team which I'm hoping turns the tide here.

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

#266

Post by ctkhn »

derf_ wrote: post #203
Schiendelman wrote: post #188

Earlier quoted context omitted.

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.

I cannot tell you how many times I've had to go through 30 hyperlinked pages of fluff explaining universal basic concepts before finding the five sentences I actually needed (buried in five different places). And just as many where people explain in detail exactly how to do foo with bar without explaining why I would want to do foo in the first place and what a bar even is.

Way too much documentation is like this. Then again, lots of times asking coworkers about an existing system or a new ticket that's not detailed properly ends up with them saying 30 pages of fluff to me before I can get to the nugget

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

#267

Post by ctkhn »

bonoboTP wrote: post #249
derf_ wrote: post #203

Earlier quoted context omitted.

I cannot tell you how many times I've had to go through 30 hyperlinked pages of fluff explaining universal basic concepts before finding the five sentences I actually needed (buried in five different places). And just as many where people explain in detail exactly how to do foo with bar without explaining why I would want to do foo in the first place and what a bar even is.

This really is one of those things that AI can improve, and already improves today.

As much as I'm not an AI booster, it has helped a lot when I hit a wall with poorly done documentation where the related bits I need are scattered all over and even a text search isn't helping me

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

#268

Post by BossingAround »

ctkhn wrote: post #265
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…

It's crazy how bad most onboarding docs are for corporate teams. I think it's a great first look the culture and how much of a hassle the role will be. The last three teams I've joined have been brutal with how little was documented or how out of date the docs that did exist are. I've had to spend up to two weeks tracking people down to find out what access group I need for our logs, deploy pipeline, etc. and I end u…

It's not very crazy to me. Most corporate teams are overrun with feature creep that "is very simple" (i.e. it takes 3x as long as estimated, because the codebase is a mixture of overengineered spaghetti for that one customer with edge-case requirements and legacy, combined with tests that are meant to be run in a jenkins job which takes 4h to complete).

Then, the engineers are expected to write the docs in between these tickets, and doc is seen as something "to be done within 30 minutes" - of course the docs will be comically (or tragically, depending on your perspective) bad.

Most people have 0 idea on how to write good docs, so in 30 minutes, they write stream-of-consciousness docs and return back to the ticket hell.

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

#269

Post by ctkhn »

BossingAround wrote: post #268
ctkhn wrote: post #265

Earlier quoted context omitted.

It's crazy how bad most onboarding docs are for corporate teams. I think it's a great first look the culture and how much of a hassle the role will be. The last three teams I've joined have been brutal with how little was documented or how out of date the docs that did exist are. I've had to spend up to two weeks tracking people down to find out what access group I need for our logs, deploy pipeline, etc. and I end u…

It's not very crazy to me. Most corporate teams are overrun with feature creep that "is very simple" (i.e. it takes 3x as long as estimated, because the codebase is a mixture of overengineered spaghetti for that one customer with edge-case requirements and legacy, combined with tests that are meant to be run in a jenkins job which takes 4h to complete). Then, the engineers are expected to write the docs in between th…

Most places I've been could have been upgraded with stream of consciousness. It's not surprising that they aren't all perfect, and the one place that was done to a very high standard was properly overdone, but at most places whatever counts as onboarding docs either doesn't exist, is essentially unusable, or directs me to legacy things that on day one I don't know enough to not bother with

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

#270

Post by emilecantin »

My recent experience with getting an app deployed from Gitlab to a kubernetes cluster on DigitalOcean was exactly like this. There were like 3 or 4 different third-party technologies I was expected to set up with absolutely no explanation of what problem they're solving, and there was a bunch of steps where I had to supply names or paths as command-line arguments with no guidance on what these values should contain (is it arbitrary? Does it need to match something else?)

Mind you, I have relatively good Docker experience (wrote Dockerfiles, have a pretty extensive Docker-Compose - based home server with ~15 services) so I'm not new to containers at all. But man, the documentation for all these tools was worse than useless.

Post reply on HN