Live data from Hacker News

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

anniemueller.com

191–200 of 455 posts

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

#191

Are tutorials like this even relevant nowadays with LLMs? I think articles of the future should be purely about approach, strategy and pitfalls, not "type in command x" handholding.

I am not sure if you thought through the implications of your proposal. LLMs are trained on examples in the training material. If something is new and isn't accessible because it lacks tangible examples the adoption rate will be lower, so there will be less training material and therefore LLMs will not be of use here. In fact, that entire aspect of LLMs is something that is not talked about as often. But is worth a w…

Software should still come with a documentation that LLMs can train on, plus they have all the learnings from interactions with developers asking about it - who will more and more just go this route (and following whatever guidance they get) and not thinking of searching for other material, let alone write guides for others. I'm not saying this is all that good, but that's the reasonable outcome.

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

#192
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…

> just watch.

You need to be brutal with yourself for this, and understand you're chasing popularity, and not necessarily revenue.

It's good to be popular with your users, but if your users are not your customers...

> I've used FAANG docs that don't come close to passing the above criteria.

... FAANG is an excellent example of which; Because their documentation and code is so bad integrations always take longer than anyone can estimate, this actually discourages managers from considering a second integration.

That is to say it's not necessarily good business to "pass the above criteria" and I think it's important to remember that.

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

#193
> In the terminal, ajkl;gawgor;iqeg;iJLkqen. wl;R aw;oeiga 4648664 arjarwgj;llj;ja fadgfgajkljl; wlj;sdjk;lfas

Open, copy and paste, press enter

> Next go to folder/hidden/deep/in/the/file/system/surprise!.file and copy the contents of the file.

Also a primitive file operation via copy and paste of the path and file content, not even requiring 1 google search to find out how to show hidden files a complete novice would need

> Next go to folder/hidden/deep/in/the/file/system/surprise!.file and copy the contents of the file.

Same primitive copy and paste operation

> The first 3 steps will take me approximately 7 hours and 193 internet searches to complete.

Everything is possible and this isn't literal, but still that's just nonsense unless you come up with a plausible scenario where the challenge isn't copy and paste operations with no cognitive overhead

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

#194
post #190

Earlier quoted context omitted.

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

I think you are misreading the parent comment here.

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

#195
post #193

> In the terminal, ajkl;gawgor;iqeg;iJLkqen. wl;R aw;oeiga 4648664 arjarwgj;llj;ja fadgfgajkljl; wlj;sdjk;lfas Open, copy and paste, press enter > Next go to folder/hidden/deep/in/the/file/system/surprise!.file and copy the contents of the file. Also a primitive file operation via copy and paste of the path and file content, not even requiring 1 google search to find out how to show hidden files a complete novice wou…

good job, you missed the point

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

#196
post #30

Most technical writers (and communicators in general) have an insufficient appreciation for the curse of knowledge. This takes me back to running a World of WarCraft guild as a teenager. We would organize "raids" maybe 3 to 4 times a week. It involved getting 40 of our guild members from all over the world to sign on at the same time, and spend hours facing off against dragons and other monsters inside dungeons. It w…

I keep saying that anyone who could run a 40-person WoW raid is almost certainly going to be a top-tier project manager. Those raids are like herding cats. Distracted, teenage cats with connectivity issues.

And they say WoW was a waste of time.

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

#197

Earlier quoted context omitted.

> Beginners have to be nurtured through lots of context that builds up slowly. My son is 17 and very interested in programming. Had to explain to him public, private, internal, and also static the other night. I then joked, you should ask your teacher about recursion tomorrow. He's with his mom this weekend, but I'm anxiously awaiting hearing how that went.

I think Java is dying. If you want to teach algorithmic thinking , teach Python. If you want to teach hardware and low-level systems , teach C.

    > 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 that run on Windows desktops/laptops

* NodeJS for lightweight backend services that run on Linux

* HTML/CSS/JavaScript (plus frameworkds) for lightweight web apps

* Python for data analysis and AI/ML work

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

#198
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…

> Especially when using docs for critical tech I only use from time to time (where I forget lots of it).

An important point easy to lose sight of when writing when that knowledge isn't lost yet

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

#199
post #195
post #193

> In the terminal, ajkl;gawgor;iqeg;iJLkqen. wl;R aw;oeiga 4648664 arjarwgj;llj;ja fadgfgajkljl; wlj;sdjk;lfas Open, copy and paste, press enter > Next go to folder/hidden/deep/in/the/file/system/surprise!.file and copy the contents of the file. Also a primitive file operation via copy and paste of the path and file content, not even requiring 1 google search to find out how to show hidden files a complete novice wou…

good job, you missed the point

Great job, you've failed to document the point.
Post reply on HN