How I, a Non-Developer, Read the Tutorial You, a Developer, Wrote for Me

To me eye, most tutorial nowadays are so a developer can put "made public contribution to <X>" on their resume or quarterly evaluation rather than helping other developers.

I'd be even happier if the original writer would simply come back 3 months later and retrace their own directions. That would make the tutorial vastly better as they will suddenly see all the little things they left out.

That has been repeated in the comments many times now, but the very headline says that this tutorial was indeed also intended for non developers.

Like some open source Github project that the author merely wanted to install, not starting to mess with the code. Basically, it is complaining in a satirical way about installation readmes, that maybe they could be made easier, that also non developers can follow some simple steps. A complaint that I can very much agree with, even though I am a developer. But so often little steps are left out and when that happens in a area you are not familiar with, then this can mean lots of wasted hours.

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 agree and when I write for such an audience, I try to be detailed and build on a proper story that they can follow through.

I do have a complaint about attempts to smoothen the DX which a lot of projects do that results in something which helps only the absolute beginner. Logs are not easily accessible or missing. It's not easy to cut/paste or grep for errors in things etc. Basically, many of of the familiar tools and techniques which people have used to find their way through things are replaced by poor substitutes in the name of making the DX better. This, I don't think is a good trend.

  > They’re more like academic papers (peer-to-peer communication of new discoveries)

Just because you have access to the text doesn't mean you're the intended audience.

Probably a good thing for us to all remember here on the interwebs where everything is accessible but written for no one

As a developer, I think most documentation is terrible both for developers and non-developers alike. And if you write your documentation so that it is useful to non-developers, it's still useful for developers.

There's no downside to writing accessible documentation, except that it requires a modicum of skill and effort. That's the real reason it's so rare, I think.

I also disagree that developer documentation is like academic papers. The ways they fail are almost opposite: academic papers are overly long and overwritten, because the authors want to be very careful and complete. Developer documentation is too short and hastily written, because they often don't care if it's helpful to anybody else.

The end result may be the same: neither are useful except to a small number of experts: the people who could probably do it themselves already, and thus may not even really need the write up to begin with. But that's a failure, not a feature to be celebrated.

   sususudododo baby shark

    bash: cd: too many arguments

`library/Lib/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam/file` and `/hahahahereiam/file.`, but neither of these boop.

Any help would be greatly appreciated.

Integrating with Linux/Windows display surfaces is disgusting however. KMSDRM is way, way better than the nightmare that is X11 and Wayland.

Knowing where to jump in your stack is a tricky question, though.

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 memory roughly looks like this I npm install something, then it tells me I have to npx (wth is that? I think that is new) install something, which gives me some weird puppeteer permissions issue. If it is permissions I guess I have to be root for the install, I try a bit more and get nowhere the same issues keep happening. Look on their website, see they have a docker as an alternative, this is a pretty newly installed computer so I have to install docker, but which one? There is 3 options and I am not sure. I try to run their docker and mess up because I do not read the documentation correctly and I have to map the directory with my .mdd file with <my-dir>:/data and this was unintuitive to me so I ignored the first part and replaced /data with my path. Again obviously a mistake on my side, but it happens every time and adds to my confusion. I look into the docs again and find my mistake. I finally get a resulting svg from the docker command. Excitement! I open the svg and it lacks all the text and I think there were also errors in the shape. Then I remember obsidian has a mermaid plugin so I thought about trying that, but the obsidian install also fails with some random error about not being able to connect to chrome.

On the other hand whenever I get a cmake project I clone it. I create a folder for the build, cd into it, run cmake <path-to-source-folder> without even looking at the documentation and it either works or I get a pretty clear message what is missing on my OS and with a short web search I can just apt install it and try again (yes this sometimes has multiple rounds) and it works!

Not necessarily. This opens you up to accusations of engaging in "mansplaining" which has broadened in definition over the years.

In addition to this, it opens you up to being thought of as a "know it all".

It's far safer, as far as office politics are concerned, to put on your coworkers the burden of asking you to clarify/explain/teach.

While sharing may be better than assuming when only considering the local optimum, if your signal to noise ratio is bad enough, you will face an impairment to communication that simply wouldn't exist if you had been more selective.

Definitely agree with this in principle. My son and I play pool (billiards) competitively. As you get better, almost nobody shares any tips because it's very competitive. I've taught him to be better than that and we have a great league team where everyone is helping the others grow.

In the mentoring (not just teaching) realm, I like to guide them into asking the questions that gets them to the answer they're looking for. When the connections in their mind light up, it's amazing.

Those raids are like herding cats. Distracted, teenage cats with connectivity issues.

    f←{⍸≠⌈\(⍴∘∪⊢∨⍳)¨⍳⍵}

Said in light-hearted jest, and not in sarcasm

But I'm pretty sure it's universal, like you allude to. And not just open-source; but at work, too. I feel like I'm the only one in my company that makes PRs to edit the READMEs to explain what a repo is for, and what repos it might relate to. (I was much happier in the past when we had a couple mono-repos; now the trend is every little project gets its own undocumented repo, alas.)

Oftentimes when the tool is typically used as part of a useful stack, the other components have documentation that can also be difficult to decode. So it becomes an order of magnitude more difficult to understand.

I can read the code, I can understand how it works but I cannot know why you decided to tackle this issue a certain way.

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, ideally with both English words and a CLI snippet.

Writing documentation is hard. Start with: Who am I writing this for?

edit: I may have misunderstood OP's "with minimal expertise" for "total beginner". They're two different things, absolutely.

On lesson I've learned from that: It's a lot about managing confidence of the user.

To do this, the instruction of "invoke this shell command" is now usually accompanied with a number of sections collapsed by default: How does a successful invocation look like - especially if it contains "ignorable warnings"? What errors could occur, and are they fatal or can they be fixed on the fly? Some more complex shell-stuff is often also accompanied by an explanation of what all of this is.

And yes, this means that sometimes one step in a runbook has a page of documentation if you read it all. But we've found that this helps a lot during onboarding new team members, as by now, a lot of the standard runbooks are also a prety good introduction to the quirks and quarrels of the normal tools we use.

It saved me a whole bunch of headaches for when other users get enrolled in these workflows.

The golden rule: Plan -> Act -> Test -> Repeat

I'll get things working locally first, but I always have to test it in docker/other fresh test env (Vagrant), just to be sure I haven't committed the same sin myself.