150 replies, and not a single mention of MCP servers? I feel like more and more tutorials are being replaced with MCP servers and expecting the user to type "connect lib pls" into their AI chat box.
How I, a non-developer, read the tutorial you, a developer, wrote for me
151–160 of 455 posts
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#152Can'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…
We're quickly approaching the point where you can have an LLM do this, and if it passes "the doc passes", if not, time to edit.
I was gonna say this. Really good idea. Having an LLM go through the docs and try to implement something. Challenge would be to prevent it from using any prior knowledge or experience, depending on the docs target audience. Good prompt is essential.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#153Can'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 was talking to a friend who is a beta-tester for crochet patterns, the business owner sends out a pattern to a trusted group and the get feedback on the descriptions and the work and any things that would make it easier before they put it up for sale.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#154This is how I, a web developer, feel whenever I'm required to build something using cmake. I guess I need to go read a book about it or something because the instructions seem different every time.
This is hilarious to me, because for me it is exactly the other way around. Just last Friday, some coworker showed me her mermaid diagrams about workflows at work. I am still not comfortable with needing to login to some website to convert some format into a useful format. If I cannot run it locally on my computer it doesn't exist for me. So I tried to install their official looking cli client. The protocol from my m…
Ok, my turn now. Let's build the project 'msdfgen' using cmake.
First step is cloning the 'msdfgen' repo. Done. Next step is reading the readme, which states "to build the project from source, you may use the included CMake script. In its default configuration, it requires vcpkg as the provider for third-party library dependencies. If you set the environment variable VCPKG_ROOT to the vcpkg directory, the CMake configuration will take care of fetching all required packages from vcpkg."
Google 'vcpkg' and end up at the vcpkg website. Click 'get started'. Land on a documentation page. This doesn't look like the right place. Click back and select 'browse packages' instead. This doesn't look like the right place either. Google 'install vcpkg windows'. Find a microsft site saying I need to clone the vcpkg repo. Ok. Clone vcpkg repo. Next step is running the vcpkg bootstrap script. Cd into the directory. Run '.\bootstrap-vcpkg.bat'. Next step is setting the environment variable. Open powershell. Add vcpkg to my path environment variable by copy pasting what the website tells me. Cd back into the original repo. Google how to build using cmake. It looks like I need to install cmake by first downloading the executable from the cmake website. Download cmake 4.1.1. Install.
Ok, it's time to run cmake. Navigate to the guide on the cmake website. It looks like I need to first create a build directory alongside my source directory. Open terminal and navigate to the folder just above the msdfgen-master folder. Run mkdir msdfgen-build in powershell. It looks like I now need to cd into this folder and run 'cmake ..\msdfgen-master'. Run it. It fails with three errors. "Vcpkg triplet not explicitly specified and could not be deduced. Recommend using -A to explicitly select platform (Win32 or x64)". Google what this means. Confusing. Look at the second error "CMake Error at CMakeLists.txt:70 (project): Running 'nmake' '-?' failed with: no such file or directory". Hmm, what is 'nmake'? Google it. It looks like I might need to install 'nmake' and add it to my path environment variable as well. Google it. It looks like I need to install "Visual C++ Development Tools". Google it. It looks like I need to install Visual Studio, and choose "desktop development with c++". Total space required: 10gb. Install this. Restart powershell and cd back into the build directory. Run 'cmake ..\msdfgen-master' again. Same errors.
If I had time, I'd continue down this path, but I know from experience that it will require another day or two of tooling around to get it working. I know I probably look like an idiot who doesn't understand cmake, but that's my whole point: it's a very confusing process for anyone who's unfamiliar.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#155"beginner". Docs are written this was are targeted at other developers who are experienced. You know this by the fact your calling yourself beginner and this isn't a friendly coding camp where everyone is making a robotic arm go up and down in python. This is being a real world developer.
To a "non-developer", yes that's what being in _this_ industry is like/about. If like taking a random coder and expecting them to read instructions to make something using crochet. There's a learning curve...
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#156As a developer, this is how I feel when I open a higher math textbook. Even though I understand that, in principle, mathematicians are using a syntax and lingo that shares some common features with computer code, my eyes slide over the words and symbols like they’re a foreign language.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#157> sususudododo baby shark
Uh oh. I'm not sure if I'm going to be able to use `sudo` anymore.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#158Earlier quoted context omitted.
I worked with someone who was great with this. They’d go through the docs and do exactly what was said, document where problems were hit and then repeat from scratch again and again. Seemed slow but their docs were excellent and I’m sure it saved more time having him hit each thing once than everyone else hitting them loads.
Funny enough, we had a hell of a time running a helpdesk where we designed the docs -- many of which I wrote myself -- to be executed exactly as written . Guess what humans hate to do? Especially the smart ones, which of course you want to employ on your helpdesk? They just would not read the damned instructions. I think this was because many of the instructions were dumb. We were explaining decades-old bank stuff. I…
Maybe being able to follow a set of (seemingly silly) instructions should be part of the interview/onboarding process. And emphasised at job performance time.
Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#159Re: How I, a non-developer, read the tutorial you, a developer, wrote for me
#160I followed this tutorial but ran into an issue where shamrock portal kept crashing. When I checked the logs, I found it would start a beep but never finish a boop. After a few hours of Googling I discovered my Debian 12's Klingon troglodyte emulator had a known centipede reported in 2013 that's never been squashed because hoobastank 34.100-6x00 actually requires it, and Debian can't move to the newer version of hooba…
It's easy to blame Hoobastank, but in my experience with these issues, most of the time the reason is you.
Perfect HN comment parody and music reference at the same time.