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…
How I, a non-developer, read the tutorial you, a developer, wrote for me
191–200 of 455 posts
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#192Can'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…
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
#193Open, 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
#194Earlier 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.”
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#195> 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…
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#196Most 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.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#197Earlier 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
#198Can'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…
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> 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