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

311–320 of 455 posts

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

#311

Post by theptip »

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 wonder if we now have the tools to build unit tests for docs now; an LLM should be able to take on the persona of a beginner try to follow your doc. For bonus points use a dumber/older model that can’t have trained on your API.

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

#312

Post by ctkhn »

skeeter2020 wrote: post #278
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…

if you're writing a new doc to "fix" this situation, you're commiting three crimes: 1. all that old documentation still exists, misleading and confusing people. you've now made the problem n+1, 2. there's no strategy to keep your new document from turning into an old, stale & out-of-date document for the next person, 3. you've addressed the wrong problem (nothing's documented!) and feel like you're superior to all th…

You're right that it's not a complete solution. The overall process on this team aren't good (we never do a retrospective, ever) and I don't get to decide how we solve #2 and #3. The best I can do is bring things up to date, keep it up to date as I run into new info or we add new systems to access, and hope that future new hires are smart enough to check created and last modified dates on documents to find the most recent one.

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

#313

Post by donkeybeer »

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…

People here are talking about it as if its merely a problem of wrong target audience when the problem is a lot of docs are straight up lies. The example setup steps and configuration in the front page itself fails. That's what makes me wish I could shoot someone or something.

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

#314

Post by ctkhn »

underlipton wrote: post #276
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…

Sometimes I wonder if it's a respect or control issue. I once worked in a non-technical position that interfaced with a complex order management system. We were given zero access to documentation and had to rely on trial-and-error and the reverse-engineered model held in the head of one specific supervisor. I'm almost certain that certain errors that appeared over and over were caused by us temporarily clearing previ…

My mother worked in engineering back in the late 80s until early 2000s and always told me about people who didn't document things because they wanted to be un-fireable. I didn't believe her or take it too seriously until some of these more recent teams, but I think it is a lot more common than it should be.

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

#315

Post by Nab443 »

BrouteMinou wrote: post #98
jiggawatts wrote: post #74

Earlier quoted context omitted.

You can achieve a lot of this by creating a blank virtual machine with "just the operating system" as a starting point and stepping through your own instructions from there. My ideal state is that for my kind of .NET work, it should be sufficient to simply install the latest Visual Studio, check out the Git repo, and press "play". That's not always possible, so then the exercise becomes to simply document each step,…

Yes, more of this! I am a big fan of the "clone, F5" and it should run. If specific steps are required, I put that in a setup.ps1, and the details in the readme.md. If the project has external requirements, I put a link to the repos, which should all be... "clone, F5"...

When I type F5, my terminal writes "~" but nothing happens, what did I miss?

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

#319

Post by tzs »

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…

Don't speak to them or help them at all?

Suppose they get stuck on the first step in a multistep procedure. Do you just let them keep flailing on that step for however long they are available, so all that you learn from that entire session is that the first step needs rewriting? Or do you end the test and let them go, again learning nothing beyond that the documentation for the first step sucks?

Wouldn't it be better at that point to help them on to the next step and then continue on having them test the rest of the steps?

Post reply on HN