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

171–180 of 455 posts

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

#171

Post by chickenzzzzu »

a96 wrote: post #127
chickenzzzzu wrote: post #33

Earlier quoted context omitted.

The language committee only makes it harder and more astronauty every year. How many Unreal Engine developers from 2007-2013 understand CPP20/23?

Reminds me of the (now decades old) humorous observation that the entired R5RS (Scheme) book is shorter than the table of contents of the C++ spec.

Lmfaooooo..... to everyone else reading, cpp programs are indeed successful, but they are successful in spite of cpp, not because of it, is my assertion. It is increasingly rare to find major applications using the newest cpp features, because of how obtuse they are for 99.9999% of people, including extremely good programmers, of which a Youtube search could produce 12

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

#172

Post by al_borland »

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've written a lot of docs, and one big issue I saw play out over several years was watching the overall skill of the team members drop. They were told by their manager to use the docs, which they did, and then seemed unable to think outside the docs when needed. For tier 1 support roles, I think the docs were helpful to get them going, but it seemed like the docs acted as a crutch for most of the team, to never be able to grow in their role and move up to tier 2. I'm not sure how to solve for this problem.

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

#173

Post by pSYoniK »

This is such a good point. I've changed jobs a lot and one thing consistently bad (to varying degrees) is documentation and tutorials specifically.

"Download X and setup"

"It's not working..."

"Oh yeah, you're supposed to do it on the remote access VM"

"It says access denied"

"Oh right, you're supposed to use the Yubikey for access"

"I don't have a Yubikey, its pass + authenticator"

"Ok, I'll email Jeff from this department you wont hear off until someone new starts. But otherwise keep following the tutorial and you should be good to go!"

It always infuriates me. At my last job I had a lot more control and authority, so I redid the entire tutorial for the proj we worked on. Every few months I'd check all my account permissions, update the list on the readme, spin up Windows/Ubuntu VMs and try to get the project running using ONLY the tutorial. Anything missing - add it.

If anyone added a new dependency the documentation would be updated and the steps checked on a new VM. I did this as we had various people come in and work for a few weeks, add a new feature and leave. The end result was that instead of 1-2 weeks to get running, people would have everything running within their first day and start work sooner. Instead of needing someone for 4 weeks for ONE feature, we could finish 2-3 and sprinkle in more tests and confidence.

I think most developers would benefit from writing for a less experienced audience, especially for this sort of thing.

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

#174

Post by ArcHound »

wraptile wrote: post #144

This is primarily the reason why I stopped writing books and started making tutorial websites. There are so many interactive tools like element that can make tutorials accessible to more people without inflating the content itself. I'm still incredibly annoyed how constrained our web knowledge is to the feature set of ancient paper technology. We can click, hover, collapse areas, play videos and react to user actions…

Hello, I am just now trying to upgrade my blog. Can you please point me to sites that do this right?

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

#175

Post by teekert »

pSYoniK wrote: post #173

This is such a good point. I've changed jobs a lot and one thing consistently bad (to varying degrees) is documentation and tutorials specifically. "Download X and setup" "It's not working..." "Oh yeah, you're supposed to do it on the remote access VM" "It says access denied" "Oh right, you're supposed to use the Yubikey for access" "I don't have a Yubikey, its pass + authenticator" "Ok, I'll email Jeff from this dep…

I've always this attitude that the one after me should not face the same issues as I had and so I update all wrong documentation, this also helps me remember how stuff works. But I have had many occasions where I just had to give up. People thought I was being annoying, my PR for fixed Readme (or even a Readme at all at times!) were simply not picked up, etc, etc.

I left that company, and left a letter for management about the abysmal developer experience.

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

#176

Post by vhantz »

Biganon wrote: post #162
bocytron wrote: post #148

Earlier quoted context omitted.

The site that got me into programming as a teenager was called "FromZero" and explained how to write programs in C for non-developpers. From installing the IDE, to how to open the console, it carefully explained each step, sometimes saying "don't worry about Snarfus, we'll get into that later". It was amazing, and I owe this website my career. That being said, I agree writing doc is time consuming and it might not be…

Site du Zéro mentioned! I always assumed it meant "a website for 'zeros'" as in "complete noobs"

I owe so much to that website. I first had access to a computer at 13, some nights of the week and only some of those nights did I also have internet access. Somehow I still discovered le Site du Zéro at that time. While I barely touched a computer the year before, I still was able to go through the whole C++ class and learned most of the basic things and reflexes I've ever needed to work in software development. That makes it really hard to listen to people who dismiss C++ because it's "not beginner friendly".

They used to have "users" who are more advanced in a class review the work of people who are behind them, and that's how you got credits to get your own homework reviewed (based on what I remember). I still daydream about building something like that, not just to learn programming, but for everything.

Now openclasssrooms is really weird, no idea what's going on on there. Their landing page is like a synthesis of every corporate website ever made. But I found an archive of the content of the old website here: http://sdz.tdct.org/

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

#177

Post by mschild »

al_borland wrote: post #172
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've written a lot of docs, and one big issue I saw play out over several years was watching the overall skill of the team members drop. They were told by their manager to use the docs, which they did, and then seemed unable to think outside the docs when needed. For tier 1 support roles, I think the docs were helpful to get them going, but it seemed like the docs acted as a crutch for most of the team, to never be a…

I think that always depends entirely on the docs and how people are instructed to use them.

From a software engineer standpoint, we have a larger collection of docs for the internal platform we run. The docs for other engineers follow the diátaxis framework [0] for documentation. Its the best approach we've found so far and the overall questions and guidance my team needed to provide reduced by a significant margin while the PRs we know receive have increased in quality and quantity.

[0] https://diataxis.fr/

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

#178

Post by devsda »

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.

> We've all been through that phase where you have to google the words you don't know.

I hope I'm not the only one who for a moment thought those were real terms in some esoteric new age programming language like LOLCODE [1]. ABCDE++ gave it away.

1. https://en.wikipedia.org/wiki/LOLCODE

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

#179

Post by throwaway2037 »

al_borland wrote: post #172
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've written a lot of docs, and one big issue I saw play out over several years was watching the overall skill of the team members drop. They were told by their manager to use the docs, which they did, and then seemed unable to think outside the docs when needed. For tier 1 support roles, I think the docs were helpful to get them going, but it seemed like the docs acted as a crutch for most of the team, to never be a…

I think that you are interpreting this outcome as technology-wise negative. Instead, I will offer a commercial positive: If the docs that wrote are so great, then you can hire lower skill, cheaper support staff. Training is also cheaper (because of docs). If I was senior IT mgmt or biz mgmt: That is a win.

    > never be able to grow in their role and move up to tier 2.  I'm not sure how to solve for this problem.
I have a selfish answer. Who cares about staff that don't improve. Really. Read that twice. Leave them behind in the dust. I am always blown away when I meet someone in my career and they have been doing some shitty support role, and they have barely progressed (career-wise or tech-knowledge-wise). Who are these people? Everyday, they dig a hole, then a 4PM they fill the hole. Rinse and repeat! Someone who is smart enough to "figure it all out" and write docs should be promoted, or moved to another support team to repeat the same pattern.

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

#180

Post by skydhash »

maxloh wrote: post #138
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 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)
Post reply on HN