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 users won't have it. (even watch them pretend to know what they're supposed to do when they don't really).
If the user achieves what they need with minimal stress/guesswork/ambiguity, the docs pass. If not, note every single place they fail, address each one, and repeat with a new user.
I've used FAANG docs that don't come close to passing the above criteria.
I've been incredibly grateful my org set this high bar. Especially when using docs for critical tech I only use from time to time (where I forget lots of it). Saves meetings, support inquiries, and video calls, because the user can self-serve.
This is just one example of how metrics can distort things, of course. Someone in management said "We want 100% documentation coverage of every method," so the staff dutifully wasted everyone's time by writing "setDefaultOptions: sets the default options". It's the kind of thing an LLM could have done better, and if you know my opinion of LLM's, you'll know that's damning with faint praise.
My own bete noire here is MSDN. It's full of overloads like "Foo(string parameter, FooOptions options) - actually useful documentation. Foo(string parameter) - does Foo with default options." But to find out what the default options actually are, you have to find another page, probably the FooOptions constructor. I wanted the default options to be mentioned on the "Foo(string parameter)" page, and they so rarely are. (A few pages are better, thankfully).
And then there is Microsoft's annoying habit of creating APIs which return the information you actually need . . . nested three levels deep inside a bunch of their own custom data structures.
I've basically resigned myself to "it makes sense in Redmond somehow, even if it makes no sense to me."
Microsoft's APIs basically shove all the implementation details onto the API user. This is, of course, abysmal API design, but "tasteful design" (in any sense) and "Microsoft" have never been in the same building. But it does make sense. And it also tells you how to interact with Microsoft APIs: the same way you interact with the hardware details that assembly languages export to the user, namely through a wrapper. (But, taste is difficult to find; that wrapper might have imbibed some Microsoft "design" by virtue of being exposed to too much Microsoft.)
Rant: if you want antialiased text, you need to use Direct2D. Direct2D is one of those APIs that waste developer's lives. You have to allocate your own framebuffer, for crying out loud. And then, you have to reallocate it if it ever disappears for some reason, and the docs don't tell you when this might happen (hot swap a video card? change monitor resolution? User moves window to a monitor with a different video card?).
I found this out developing a cross-platform UI library, https://github.com/eightbrains/uitk, leading to my above conclusion that the only proper way to relate to the Microsoft API is through some layer.
> But to find out what the default options actually are, you have to find another page, probably the FooOptions constructor. I wanted the default options to be mentioned on the "Foo(string parameter)" page, and they so rarely are.
It's better for maintenance (of the documentation) if the default options are only described in one place. (If the defaults change in a new version, this ensures the documentation doesn't have inconsistent, wrong descriptions. The analogous reasoning, applied to the code, is probably part of why the FooOptions class exists in the first place, after all.) But they should do you the courtesy of linking there.
This is only a problem if you write it twice. Instead you can write it once and display it twice.
Hell, I even do this on my github.io website that uses markdown. You can just write some text in one document and read it in another.
We're programmers, so we should be lazy. It's about being the right lazy. You can be lazy by putting of a task today that takes more effort tomorrow or you can be lazy by doing a task today that takes less work than it would take to do tomorrow. Most people choose the former and wonder why they have so much work. In programming if you're doing redundant work then you're probably being the first type of lazy
Some varieties of in-code documentation do support links, e.g. XmlDoc which is the de facto standard for documenting C# code (and therefore the most relevant to my comments about MSDN because I was referring specifially to the .NET API documentation) has multiple ways of embedding links in your in-code documentation comments: https://learn.microsoft.com/en-us/dotnet/csharp/language-ref...
MSDN even uses those, a lot. But not enough. I wish that every time they had a "Foo(string parameter) - uses the default FooOptions" it was a link to the documentation section where the default FooOptions are listed. But usually you're left to find the default FooOptions yourself, which means 5-10 minutes of digging through docs (1-2 minutes if you're lucky) that I could have spent writing or reviewing code instead. That adds up.
We are talking about MSDN not some source files. Even if those pages are generated from in-code documentation that generation step can use whatever transclusion mechanisms Microsoft wants to add.
Related to this is the omitting of units. I encountered something like this in the Android SDK (years ago, dunno if it’s still like this).
setFontSize(float): sets the font size.
Cool. Sets the font size in what? Points? Pixels? Device-independent pixels? Which of the 12 different types of measurement Android supports is used here? I can’t remember exactly what it turned out to be, but I know it wasn’t the unit I expect for fonts (points).
In similar cases (maybe not exactly here), I suspect the author also didn't know and didn't care to look it up and just wanted to tick the box that it's now documented.
This is why I rage against the crowd that promotes "self documenting code". There's no such thing, even if you should strive to make your code as readable as possible. But if there's a way to misinterpret it then you can bet many people will.
The biggest problem is that this ends up creating so much extra work. An extra 2 seconds from the dev could save hundreds or even thousands of people hours of work. I can't tell you how many hours I've spent chasing stupid shit like your example. I don't know a single programmer who hasn't.
I just don't understand why everyone's frustration with documentation (or lack of) doesn't make obvious the importance of good documentation. Every single one of us has experienced the wasted time and effort that results from the lack of documentation or from low quality docs. Every single one of us has also reaped the benefits of good documentation and seen how much faster it makes us. How does anyone end up convincing themselves that documentation is a waste of time? It feels insane
This kind of bad documentation is actually way more common in teams that require doc comments for all code, which are then promptly auto-generated by the IDE and never filled with actually useful information.
Self documenting code in this case would mean using a type that encodes the unit - which would have the additional benefit that the compiler or other tools can now check correct usage.
Requiring docs isn't the cause of the problem. It's the lack of enforcing quality. The difference is that you're looking at the metric and seeing Goodharts Law in action while there's nothing preventing you from going beyond the metric. That's the real issue is that metrics only take you so far. No metric can be perfectly aligned so it's up to the people who are evaluating the metrics to determine if the letter of the law is being followed or the spirit of it is. If you do the latter then yeah, maybe some functions will be left without docs but you also won't hasn't those tautological docs either. If you only care about the letter of the law then you should expect the laziest bullshit as Goodharts Law always wins out.
Stop reading too much into metrics. Metrics are only guides
That's more about API design than about documentation though, as with a proper function name/using value objects/something else, you already know what the correct value to pass is.
It's a widespread issue though, where the API designer doesn't clearly communicate either what the thing does and/or what the thing needs.
If you don't need the docs then you don't need them, but sometimes we all need a "hey bro, I know you're a little lost so I'm going to break down what's happening in plain English". At a certain point you just don't have the entire code base in your head all the time and you need a reminder on what exactly the Flargle team does to all the Nargs.
This is why I'm sad that hungarian notation has gained into such a bad reputation. Sure, you can overdo it, but a `duration_ms` or a `response.size_bytes` or a `max_memory_mb`, or an `overhead_ns` is so much easier to use.
Better yet would be unit-aware types. Then instead of
duration_ms = 1000
you can have
duration = 1s // or duration = Seconds(1) in deficient languages
and it's either a compile error or the type system enforces the correct conversion.
As for the bad rap of hungarian notation, it's mostly from people using it to encode something that is already clear from the types. "fDuration" helps no one over just "duration".
That’s just a C enum interfaced in Swift. You can’t instantiate it, and it has no methods or any kind of functionality. It’s effective a list of numbers.
What are you expecting the documentation to say here? It will make more sense when you find where it’s used.
? Did you read the link? It’s used to query collections of keys grouped by the KeySpace categories, instead of a single item per key. Makes sense to me.
There’s plenty of other poorly documented Apple APIs (io_surface), but this isn’t one of them.
The struct is only named on the link you provided, not documented. So thanks for showing the absolute irony of it not being greatly documented, allowing people to misinterpret what it means.
Because it’s a boring enum in C, auto translated to a swift struct.
And if you’re reading the documentation because you do development, then you would already know that the header files are installed on your computer and you can trivially verify that there is nothing to document because it’s just a query key.
And we don't even have to get exotic for that. My language, Danish, is just a run-of-the-mill Germanic language and those terms are "faster", "moster", "fætter", and "kusine".
Some of the East Asian languages are crazy regarding terms for family members. It's like learning foreign words for plants: I just give up. I will not even attempt to learn them.
There are also languages where the relative age difference changes how you address a relative. Like if your father is older or younger than their sibling, the way your address that uncle or aunt changes. There is another way you address them if they are the oldest or youngest uncle/aunt. Similar but slightly different on the mothers side.
Presumably those enums are used to select localized labels and you need all these cases to cover unique words / phrases that exist in the supported languages for specific familiar relations.
> with Xcode, go to fargler settings click on narg screen
I hate how this looks "accessible" to people in theory, but in reality finding those screens is more like playing a hidden object game.
Also, I hate how those things keep changing around in all kinds of software, but especially Apple. Somebody probably thinks "yeah maybe we should move the Fargler settings from the Narg to the Birp screen", and makes dozens of internet "documentation" (and sometimes their own!) obsolete.
One problem I remember from (briefly, fortunately) dealing with Apple APIs is wondering incessantly why every API (I was looking at) started with NS. Admittedly these days any AI would tell me it stands for Next Step. But if you are creating a new thing with a quirk like this please explain it once, in a place that's easy for the student to find.
b) but giving people namespaces is unironically bad because it's what lead to "enterprise development" style APIs like C# where everything is named System.DataStructures.Collections.Arrays.Lists.ArrayList, as if giving something a longer name makes it more professional.
c) so instead two letters means a system framework and three letters means a user framework
I quite like a terse but consistent conventions myself. I remember finally being able to quiet the tedious part of my brain that couldn't get past the NS conundrum when I finally came up with the NextStep thing as a reasonable theory.
In other words, my only complaint is that this Apple convention is not more easily discoverable. Or perhaps that the expert author of the book I was reading (this was back in the day) didn't feel the need to share it with his readers.
The issue here is that people are treating reference materials as tutorials intended to cover your exact concern at the moment. You are expected to know what a narg is and what flargling means. In more real terms, the documentation for screen savers https://developer.apple.com/documentation/screensaver?langua... won't explain what a view is, what subclassing is, or what a Rect is. Those are required knowledge to consume the documentation and it's not a documentation failure that this is true.
No, you missed the point. The problem isn't "narg" or "flargling" - those are just random stand-ins for normal words. Instead the problem is that the description says nothing that isn't already said by the symbol name. Whether or now you know what "narg" and "flargling" mean, a documentation page for Nargflargler that just describes it as "Flargles the narg" provides zero additional information to you.
> Do not speak to them, certainly do not help, just watch.
Sounds simple, right?
I ran usability tests at a past company and have seen people who were incapable of blurting out explanations, pointing at the screen, even audibly grunting or whining to themselves when the participant made an incorrect guess about what something meant. One even grabbed the mouse.
Having a neutral moderator can help as it allows the people who made the UI/docs to stay on mute or on the other side of one-way mirror.
But I'd still suggest learning the "just watch" technique. If you master that and wish to take the next step, look up "think-aloud protocol".
If you let someone flounder on one task indefinitely then you don't learn anything about subsequent tasks. But if you correct them too quickly you won't uncover the other approaches they would have tried to complete the task. Most research plans define cutoffs such as:
1. Participant expresses extreme frustration or gives up
2. A couple minutes have elapsed from the first failed attempt
3. Participant unsuccessfully attempts three distinct approaches
If the test reaches one of your cutoffs then the interface/docs have failed the task and the moderator can skip to the next task or question. Sometimes they'll also offer to show the participant the expected solution or explanation.
Exactly. You want to learn as much as possible from each study. Explaining too soon reduces amount learned, as does ending the study early because a small hint wasn't provided to get to the next step.
> You can also record it to show them later, but for various reasons it doesn't resonate quite as strongly when it's not live.
Yeah, because it's wasting my time having to watch people who literally have never heard of something as basic as keyboard shortcuts. It's fine if I actually have the time to explain to some Gen Z kid how Ctrl+X/C/V works, but being forced to sit around and watch someone with that level of non-understanding of how a computer works when I got a full backlog of shit to do is just agonizing.
With a video recording, I can at least go forward and see where they actually have problems with stuff that is in my influence and skip over the utterly boring moments that are just wasting my already limited time.
Before I saw your response I removed this sentence from my post as I realized it was not central to my main point. However, I still agree with it and am happy to explain why.
> wasting my time having to watch people who literally have never heard of something as basic as keyboard shortcuts
First it depends on whether the audience for your product includes people who do not know keyboard shortcuts. If that's not your target audience then the rest of the test may not be valid anyway.
Otherwise, there is utility in forcing yourself to watch your users struggle with your product. The best product developers/owners I know have a bottomless appetite for observing people use their product, even if doing so means deferring the rest of their "full backlog of shit". Perhaps they're less efficient in the short term at churning out lines of code, but the understanding and empathy they develop makes them significantly more effective in the long term.
It's like how expert athletes often watch videos of themselves or competitors (when applicable) to understand the nuances of their play - once you understand something very deeply the small things start to matter more, until they dominate the game.
If you are a master of UI/UX and you are observing a user doesn't go through the paths you've created its an opportunity - you might be able to learn something that would make your approach more successful across a host of different users that up to this point you clearly are not winning the game against.
If you take an antagonistic approach and curse the idiot for making you watch you have not even put on a jersey yet.
This is our documentation workflow as well: Write it, and then have someone less or not experienced with the system execute the runbook. Also, encourage everyone to work on refining and improving the docs, because after 5 years with a system, I will have blind spots someone less experienced can point out.
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.
A good first exercise for new hires! (And I say that as having been both a new hire who's updated the documentation after trying to execute it, and as someone who's guided a new hire when the documentation proved inadequate.)
Any kind of documentation has a target audience. Your test is very valuable if and only if the target audience is a total beginner. Of course it's still very hard to write good documentation even if you have identified your target, but having someone totally illiterate on the subject matter review your documentation is as useful as if I'd have to review a PhD thesis in quantum physics. It just doesn't make sense (trust me :).
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.
For most public documentation, you don't get to pick your audience. You think you'll have people with certain experience, but then it turns out you're wrong. Usually a lot of the time. And even when you're not wrong, having the steps essentially from scratch listed out reduces the number of times people get stuck, because they think about things they may have missed.
I cannot tell you how many times I've had to go through 30 hyperlinked pages of fluff explaining universal basic concepts before finding the five sentences I actually needed (buried in five different places).
And just as many where people explain in detail exactly how to do foo with bar without explaining why I would want to do foo in the first place and what a bar even is.
Way too much documentation is like this. Then again, lots of times asking coworkers about an existing system or a new ticket that's not detailed properly ends up with them saying 30 pages of fluff to me before I can get to the nugget
As much as I'm not an AI booster, it has helped a lot when I hit a wall with poorly done documentation where the related bits I need are scattered all over and even a text search isn't helping me
I was gonna write something similar. Know the audience. I've also come to the conclusion that "total beginners" (and certainly "minimal expertisers") didn't nowhere to read the docs anyway so it didn't matter.
In other words, people who are used to reading docs can read (good) docs just fine.
Yes, of course, good docs are a must. They are critical to success. But not all docs have to explain how to use a right-mouse button.
Perhaps in addition to a description of the expected audience, it might be an idea to list some assumptions made about the reader? e.g. has installed software previously, confident with bash commands, &c
I almost systematically use BLUF (Bottom Line Up-front) when I write docs, I think I'll make TABLUF a thing from now on (Target Audience and Bottom Line Upfront) :)
The experts are likely to be skimming and interpolating your doc, so they'll get through it but you won't know why. You won't know if your doc works, or if it even addresses the subject matter. This is also true of academic papers.
My mom taught CS in the 1980s, and told her students on day one: "Computers are stupid, they will only do exactly what you tell them to do, not what you want them to do." Program code is, in a sense, a tutorial for an utter beginner. The benefit of coding is that you can do the "beginner test" over and over without wasting anybody's time, so you know that the computer will get through it. But an expert (including yourself) might read that code and never see that it does or doesn't work.
It's crazy how bad most onboarding docs are for corporate teams. I think it's a great first look the culture and how much of a hassle the role will be.
The last three teams I've joined have been brutal with how little was documented or how out of date the docs that did exist are. I've had to spend up to two weeks tracking people down to find out what access group I need for our logs, deploy pipeline, etc. and I end up writing up a new doc that's good for its point in time, immediately becomes out of date when someone adds a new system or access group but doesn't document it anywhere.
The one team I was on previously that got me everything I needed in about two days was great, but it's sad that this isn't the norm. Everywhere else has been pretty hostile to getting set up, and the poor onboarding experience has been a preview of the developer experience. My current role is standing up a new devex team which I'm hoping turns the tide here.
It's not very crazy to me. Most corporate teams are overrun with feature creep that "is very simple" (i.e. it takes 3x as long as estimated, because the codebase is a mixture of overengineered spaghetti for that one customer with edge-case requirements and legacy, combined with tests that are meant to be run in a jenkins job which takes 4h to complete).
Then, the engineers are expected to write the docs in between these tickets, and doc is seen as something "to be done within 30 minutes" - of course the docs will be comically (or tragically, depending on your perspective) bad.
Most people have 0 idea on how to write good docs, so in 30 minutes, they write stream-of-consciousness docs and return back to the ticket hell.
Most places I've been could have been upgraded with stream of consciousness. It's not surprising that they aren't all perfect, and the one place that was done to a very high standard was properly overdone, but at most places whatever counts as onboarding docs either doesn't exist, is essentially unusable, or directs me to legacy things that on day one I don't know enough to not bother with
if you're writing a new doc to "fix" this situation, you're commiting three crimes: 1. all that old documentation still exists, misleading and confusing people. you've now made the problem n+1, 2. there's no strategy to keep your new document from turning into an old, stale & out-of-date document for the next person, 3. you've addressed the wrong problem (nothing's documented!) and feel like you're superior to all the jerks who came before you.
>> My current role is standing up a new devex team which I'm hoping turns the tide here.
I'd love to know what you're doing different that can help with this problem. Writing more, new documentation is unlikely to be it.
You're right that it's not a complete solution. The overall process on this team aren't good (we never do a retrospective, ever) and I don't get to decide how we solve #2 and #3. The best I can do is bring things up to date, keep it up to date as I run into new info or we add new systems to access, and hope that future new hires are smart enough to check created and last modified dates on documents to find the most recent one.
Sometimes I wonder if it's a respect or control issue. I once worked in a non-technical position that interfaced with a complex order management system. We were given zero access to documentation and had to rely on trial-and-error and the reverse-engineered model held in the head of one specific supervisor. I'm almost certain that certain errors that appeared over and over were caused by us temporarily clearing previous ones incorrectly. This was especially frustrating because we were 2nd shift, so dealing with those errors could mean the difference between getting home that night or getting home the next morning. It was hard to tell where along the line between, "They're not sophisticated enough to make use of them," and, "We don't want our processes leaking," we fell, according to the higher ups.
My mother worked in engineering back in the late 80s until early 2000s and always told me about people who didn't document things because they wanted to be un-fireable. I didn't believe her or take it too seriously until some of these more recent teams, but I think it is a lot more common than it should be.
Reading through bad setup docs is 10x more stressful when they are part of new employee onboarding.
I’ve always advocated for new employees first contributions to be fixing problems they had in these setup materials. They are coming in with fresh eyes and no context so they are the best possible reviewer
My first ever software developer job, I was hired with basically no knowledge or experience to learn (I was very lucky). I knew MS-DOS command line pretty well from my childhood, but hadn't ever used POSIX. I was given a macbook air and some docs to follow.
Trying to follow the docs, supplementing with a lot of googling, I somehow managed to remove the tar program from my system. This broke literally everything. Had to stop halfway through the multi-day process to do a clean reset and start over from scratch.
We called this the “receptionist” test decades ago at the small company I was at - after we though we were done we’d give it all to the receptionist and ask her to use it; and we’d hang our head in shame at everything we forgot and head back.
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.
I am that guy. I will also say from experience: It does not pay. Never once has it been ack'ed in a year end review (which controls bonus, salary increase, and promotions). As soon as a manager sees you as "The Wiki Guy", they take you for granted. As I grow older and more cynical, my view on internal docs: (1) Write them for yourself. (2) Write them to make people go away when they ask you questions ("Did you search the Wiki?").
I had this issue during a job interview exercise. Their "follow these steps exactly" were simply broken. The root cause was that they were having people re-use the same shared remote amazon desktop system. Each candidate got their own home directory, but they wouldn't just reset the image between candidates. The person before me had used up 98% of the drive space. When I followed the 'step by step' guide, nothing worked, because it was out of drive space, but... I wasn't seeing 'out of drive space' messages directly - I was seeing their 'setup shell scripts' looking like they worked, but then nothing did.
I honestly thought this was some sort of trick exercise to see how I deal with broken processes, and I was writing fixes to their docs and shell scripts to deal with error states, and reported back to the person. I initially got a 'no, this isn't that sort of test. the docs work, just follow them'. After more back and forth, I got 'oh, I see that might be broken, yeah, just carry on'. I fixed what I could, made a couple commits back up, but was then told my commits needed more context, which I then added, and promptly never heard back from them again. Until... weeks later, HR reached out to say "we've gone with someone else". I recounted this story and got at least some semblance of feigned shock of 'that's not how any of this is supposed to go'. I'd kept some screenshots and emails, but they didn't care to go down that road.
tldr - Employers giving tests, please run through your own exercise processes now and then (or maybe even automate them with some smoke tests).
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. It didn't make sense, but it's what you had to do! So these guys tried to 'fix' it, and in doing so, broke it.
The whole support model was predicated on this idea that the 3rd level guys would write stuff that the 1st level guys would slavishly follow. It never worked.
You could probably fix this, to some extent, by adding a sidebar to the instructions that 1) acknowledges that the procedure doesn't seem to make any sense, and 2) points out why the seemingly obvious fixes won't work. That's usually immensely helpful to me as a reader, so I don't have to waste time wondering if I misunderstood the instructions or the author misunderstood the procedure.
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.
Problem is a lot of times silly instructions are silly because they are wrong. Like why did you turn left and try to drive through that river? Those instructions assumed a bridge was there but it washed away 10 years ago. A new bridge exists, you can see it, obviously take that one instead.
You can achieve a lot of this by creating a blank virtual machine with "just the operating system" as a starting point and stepping through your own instructions from there.
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.
I agree that testing from a vanilla machine is important.
But there's also that your language to the user doesn't necessarily say what you think it does. You can't read it from the position of someone new. Only someone new can.
And a set of commands to paste to CLI isn't the full extent of what we usually mean by documentation.
In case you weren't attempting to make a point through irony, GP appears to be using "F5" informally as shorthand for "instruct your IDE to attempt to build and run the code". Presumably, that kind of documentation wouldn't normally literally say "F5" there unless a specific IDE had already been prescribed. The point was simply that the user shouldn't be required to do anything manual to set up the code, when starting from scratch, except perhaps to authorize the automated setup procedure.
If i'm gonna untangle something, i may as-well write some notes. If i'm writing notes on it already, i may as-well refine the grammar a bit and update the docs. It's really quite small effort compared to the main work of learning the system, so i don't quite get why so few people do it.
I'm ... confused what you mean. If the junior is gonna untangle the docs anyway, why not make them directly update the parts that confused them once they're through it.
I apologize; I misunderstood. I thought you were making a “fend for yourself” argument; I was not associating “junior devs on the team making the docs, need to fix docs or make good ones”.
They're not necessarily prohibited from asking questions if they're stuck, though. But also search in the chat channels for similar issues.
Updating docs in source control also onboards folks to code review. It would be weird to update docs and get a hostile reception.
While nice to walk through with someone and conduct a usability study, just leave it better for the next person (who could be yourself, if you forget). That has happened before.
I'm a Jr. sysadmin at a medium sized software company.
Whenever I document workflows for our users, I have two colleagues of mine who have no connection to IT work through them and add the small gotchas they asked me to the docs.
It saved me a whole bunch of headaches for when other users get enrolled in these workflows.
I've been doing some cal/QC functions recently after years not touching it. Since I last did it I've forgotten some of the knowledge that is just assumed. The answers to my questions are documented, but not in a places that is accessible from the production side and has lived as community knowledge in production. I've been making a list and updating the documents to fill in some gaps.
Unfortunately some of the production people aren't comfortable enough pushing for changes in the documentation so some of my job now is to ask what they've noted and get it added.
I'll go against the grain and say that fumbling is how you learn. The easier it is to get to the end of the tutorial, the less you learn in the process. If you learn math from a bad book, you have to organize your own notes, to untangle the mess. If it's laid out all neat and clear like a straight highway, you never wrestle it out with the concepts and you don't learn.
That's something I came to accept as well - deeper understanding will only come from challenge. Unfortunately, there isn't always the opportunity to let people fail, and that opportunity is definitely not in a set of reference docs.
I like to always provide a docker image which can be used to execute whatever solution I'm developing. Most of the time the docker image isn't even used, but it's an important exercise because I'm forced to run my solution on a fresh system, so the resulting docs will invariably be more complete, and it also documents the dependencies in a way you can easily verify.
This is basically the user testing approach as described in "Don't make me think" by Steve Krug. You can use it to test usability of your applications as well.
Suppose they get stuck on the first step in a multistep procedure. Do you just let them keep flailing on that step for however long they are available, so all that you learn from that entire session is that the first step needs rewriting? Or do you end the test and let them go, again learning nothing beyond that the documentation for the first step sucks?
Wouldn't it be better at that point to help them on to the next step and then continue on having them test the rest of the steps?
I am stuck in an organization for some personal reasons.
The first thing I noticed when I joined was the culture of "Please ask when something is not clear".
After was given a quick overview in person.
You guess: almost everything is unclear. A mess. Need to ask a lot. Task descriptions, purpose, reasons, whys, wheres, what does this comment mean, why are these things contradict each other, and so on, and so on.
And except asking KG, usually the answer is: ask XY. Or KG.
People always busy, always in rush, give a condensed answer raising the same amount of new questions that it answers.
When KG is out, productivity slows down.
And all this beyond the usual in a meeting, out with customer, on holiday, sick, the children is sick, held up in a traffic jam, car broke down, need to finish project P so schedule something for next week, and all those kinds of common things making the relevant person unavailable when "something is not clear".
And beyond the forgetting 4 things of the 15 new info given by the time we are finished with the converstaion. No written trail to look back at.
When 3 person paint a complete picture then all above happen three times in a row, or in a never ending loop.
Productivity suffers, quality suffers, I will leave as soon as I can.
Positive things? Probably that the expectations are low. And they pay well. And by now I am irreplecable in a local subset I was hacking together (I do not call it work or development), not even KG can help others there! I will leave on my own terms (as usual, unluckily).
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 whole system. The situation is even worse on Android, where there are dozens of standard APIs to achieve the same functionality.
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)
As far as I recall, many libraries in the Java ecosystem, as well as the Android API, don't have the official tutorials or guides you're referring to. The JavaDoc and the Android API reference are often the only officially available resources.
So no, Those aren't just there to refresh developer's memory. In many cases, they are the only resource for learning the system from scratch.
This is a great phrase. I fully agree with your sentiment. To me, I never read Javadocs in HTML-only form. I always read them in an IDE, along with the library code in question. If anything is unclear from the Javadoc, then read the code (which immediately follows the Javadoc).
> Usually you look for code examples or a guide for learning how those work
... which in practice means, particularly for stuff that recently changed, that you go to StackOverflow only to find out that the majority of posts are horribly outdated and don't even compile any more.
The other side are code examples that technically work and show, say, the syntax on how to use a programming language's or framework's shiny new feature... but manage to dumb the code example down so far that one has a very hard time wrapping around one's head on how to use this feature in a real world application.
I was reading The Art of Unix Programming (E. Raymond) and one of the advices was that every library should come with a program. So even it’s a todo list kind, I think it’s quite nice to have.
I started a company to do exactly this a few years ago, and got to work with amazing companies testing their developer experience.
The problem is not the docs, it's Conway's law. One team designs the API, the other team designs the portal, and another team designs the SDK. The user has a holistic experience that cuts through each team.
That, and the docs are usually written first by the most technical person around, who has a hard time sharing the world view of a noob.
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.
I do think a lot of developer tutorials and documentation don't take into consideration that many people might not have a common understanding of terminology especially if the reader is coming across this problem or process for the first time.
Fully agree. Good docs are essential for scaling a team beyond the first few hires. I always make a point of filling in all the gaps I had to gather myself during my onboarding, and ask the next hire to do the same (and carry it to the next hire, and the next) this helps keep the docs up to date with the relevant knowledge since it’s always being filtered through the lens of a brand new computer and a dev with minimal context.
People here are talking about it as if its merely a problem of wrong target audience when the problem is a lot of docs are straight up lies. The example setup steps and configuration in the front page itself fails. That's what makes me wish I could shoot someone or something.
> 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
And if you have access to user experience researchers, go talk to them! They are experts in running this kind of scenario, and can help you avoid all the pitfalls that might bias your results
Totally. Something that I see a lot is software that tries to read a config file during startup that bails out (sometimes with no error message!) if the file doesn't exist. Or tries to write the config file into a directory that doesn't already exist.
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.
Play testing is the most important part of game development. Indies who struggle to come up with concepts are really sleeping on this. If you run play tests well enough your roadmap will almost write itself. Players will do and ask for things that you would never dream of.
I think an intense culture of playtesting is why valve software puts out games so rarely. Their new strategy seems to be to keep a title semi-secret for years while a small army plays it full time. If Deadlock makes it to market, it is almost certainly going to be an acceptable game to most who are even remotely interested in the genre.
I wonder if we now have the tools to build unit tests for docs now; an LLM should be able to take on the persona of a beginner try to follow your doc. For bonus points use a dumber/older model that can’t have trained on your API.
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.
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.
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.
In the past (20 years ago), those tier 1 roles were a great feeder for the organization. Because that role touched so much, it meant everyone had a lot of perspective on the organization as a whole, and thought about support and maintenance while building new things.
It’s easy to say who cares and hire from the outside, but that organizational context and care for support is lost. People build whatever and throw it over the fence, which makes everything worse, imo. Those people also tend not to stick around, so they have no skin in the game and it’s hard to develop culture as people rotate in and out frequently.
There are always some people who will never learn, and these people are cheaper, but there are other hidden costs as you seek to optimize for low-skill workers.
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.
Correction: They are quite good for this: Easy beginner level stuff. For that specific thing, they are much MORE correct than they are wrong.
The status quo is a moving target. 6 months ago what you said would be fully correct. This is no longer the case, now you are only sometimes right and mostly wrong. It is getting better.
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.
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.
Without AI, it was really hard to get to understand some docs. Today if you don't use AI for these situations shrugs
Most cases it is not that docs author forgot users wont have same toolchains. Simply do not bother reducing config files to share just source code. Indirectly pushing users to make use of same tools.
Hopefully in 20 years no one will be going to check the source code of anything, and programming is elevated even more.
50 years is crazy amount of time, to stay this primitive. Tech shouldn't just evolve for end users.
Most tutorials are not for non-developers, they’re for other developers who are also in the ecosystem. They’re more like academic papers (peer-to-peer communication of new discoveries) than they are like a pop sci book or show meant for a general audience.
And that’s okay! Great even! As a fellow peer I benefit greatly from those tutorials. Sometimes even from my own notes published and forgotten years ago.
This is why courses and other structured learning materials exist. Beginners have to be nurtured through lots of context that builds up slowly. If every article had to start from scratch, we’d never get to anything interesting. By the time we got to the interesting bit after 30,000 words of preamble, you’d be long gone as a reader.
And the very next reader would complain that the 30,000 words were not enough introduction to the topic. They needed 40,000.
Ah, the infamous public static void main(String[] args). Hopefully the next generation won’t need to learn all those concepts up front with the introduction of instance main methods in Java 25.
I actually think the inscrutable Main method in java has some value. As a kid, I loved to know how things worked and always did things like read instruction manuals and read ahead in school textbooks. I wanted to know everything about anything, and I wanted to know how it worked from the bottom up.
The java main method taught me "This is abstraction, an important concept in programming. You won't always know how all the magic works all the time"
It taught that you have to deal with black boxes.
Also, I never saw it cause problems in CS101 classes, because the kids curious enough to want to know something their professor didn't explicitly talk about were usually the ones who would do fine at learning all the parts of it.
The kids who struggle with programming never seemed to have problems following "Just write your code here, you will learn more about it later"
He’s starting with Java? I wonder if that’s the right language to start with. What is he most interested in doing? Anyway thanks for nurturing the next generation.
I fully disagree with Java as a starting point and it was an interesting conversation with the teacher.
Apparently, "College Prep" courses more or less determine that Java is the language that they should use.
His teacher thought it was stupid as well, but sometimes your hands are tied. That's what the schools are using as a starting metric though.
He was apparently the only person in the class that said he wanted to do software engineering. Don't worry, he'll be a polyglot before he reaches college.
I learned Java in uni and think it's a fine language to start with. It's also been modernized a lot in the past decade, and if you really want a more modern language it's easy to transition to Kotlin.
I'd take Java over Python or JS any day. It wins on performance, it wins on type system, js is just a plain trash language not at all suited for general purpose programming (TS solves some problems but not all and it has its own problems) and python is fineish but it's slow and just kind of icky, I'd never do serious software development in python. It's fine for small scripts and notebooks and such, we learned python as part of our math classes while the programming classes focused primarily on Java. We also had a class on web development using JS, ML using Python and windows programming using C++ and C#.
I struggle to see any significantly better candidates for a first language than Java. Sure you could go with C but nobody really uses it any more outside of niches. C++ is out, too much stuff. I really like C#, it's my daily driver and I wouldn't mind it as a first language but I think Java is more approachable for beginners. Less confusing syntax to learn. I don't know Go but maybe that could be an alternative? Other than that I'm a bit out of options.
Java is a fairly simple language that's easy to learn and allows teaching a lot of important concepts that will be useful in other languages moving forward. That's a big thing I think, it's not meant to be the only language. The word polyglot is used some times, to me it just means programmer. I don't know any competent developers who only know one language. You end up learning multiple and I think Java is a good entry point.
C# is amazing. Decisions at the education level were made well before it went cross-platform though (FWIW, I've been using it since before v1.1).
Would be interesting in what confusing syntax you're referring to. I think one of the beauties of it is that it's additive. You can program plenty of simple stuff in it with conventional style code, but there's a lot of syntactic sugar available that makes things so easy when you need to start scaling things.
I agree, C# is my language of choice and I've been using it professionally for over 5 years. I use it for personal projects as well.
I'm referring to all the stuff C# has that Java doesn't. Async, ref/in/out keywords, extension methods, linq, lots of stuff. Maybe it's not a big deal, like I said I wouldn't really mind it. I just think Java is a bit simpler in this regard which is an advantage for beginners.
Some differences where I prefer java are checked exceptions and imports. C# usings are ambiguous, it can be difficult to figure out where things are coming from for code samples outside an IDE. And checked exceptions are just good IMO. I've never seen why people dislike them, having used Java and C# I think Java does it better. It's easy to miss exceptions in C#, I wish library developers could use checked exceptions to tell me which exceptions I should worry about.
Anyway both languages are great first languages and great general purpose languages. Highly recommend both.
Thanks for taking the time to respond. Ultimately though, most of those aren't required from the beginning, but the syntactic sugar, abstractions, and performance gains from them are amazing.
You probably already know, but I'll opine a little bit about extension methods. I use them a lot.
Entities > Repositories > Functionality. All split out.
- Entities (pretty much just gets and sets, nothing more than necessary).
- Repositories via extensions to determine where the data comes and goes from (some data comes from SQL, some from Redis, some from Postgres, doesn't matter since it's split out) and any particular queries you need for optimizing things.
- Functionality via more extensions without adding additional code to the entities.
Separation of purpose/use.
I may or may not have completely replaced our data layer in the middle of the height of our season with no interruption. Little bit passionate about this one.
Java's a pretty good beginning programming language. Outside of the mystical incantation of `public static void main(String[] args) {` and what the difference between `new ArrayList` and `ArrayList.new()` is (I still don't know but I haven't really touched it since college), it's a good statically typed imperative language that you can throw objects and functional stuff into when it's time, isn't going to give you weird errors about indentation, has just enough pointers for you to learn how to avoid a `NullPointerException`, does things pretty "conventionally" (ie, there's not a lot in Java that doesn't also show up in other languages), and is easy to compile and run (when you're not using 3rd party libraries, which students in something like a Data Structures and Algorithms class aren't going to be using). Ideally you have another class teaching you another language too so you get the double bonus of learning what a language is and what a language isn't, and Python's good for that, but by itself Java's fine
> Outside of the mystical incantation of `public static void main(String[] args) {`
I don't think it's mystical. If you don't have an instance of the class yet, you need a starting point and static fills that void (lol. I'll show myself out)
My first programming class was Java. That was 8 years ago. Maybe the curriculum designers thought Java would be relevant for the workplace? The education system always lags several years behind industry trends.
> Had to explain to him public, private, internal, and also static the other night.
Access modifiers are sort of a dying breed in a lot of places aren't they? We use Go, so we're obviously still using the two it comes with, but it's public vs module only and fairly intuitive. Every other language we have in production, doesn't make use of access modifiers. Similarily while static is a thing in Python, it's hard to see what advantages it brings compared to a free function if you're using a programming language that doesn't require you to have object instances to call non-static functions. Obviously access modifiers will stick around in a lot of organisations, but there will be plenty of jobs where you never have to work with them.
The way Go handles modules, is frankly one of the few language feature of any language I've ever worked with that I wish was in every language I work with. It's so easy to use and so hard to mess up. Ok, I guess it's not hard to mess it up, but it's not intuitive.
Access modifiers are useful, albeit not for beginners. They're most useful in statically typed languages with good tooling where they keep auto-generated API docs and autocompletions clean.
Static methods are useful for namespacing, e.g.
var instance = SomeThing.fromString("...")
In some languages you can of course make a global free function called someThingFromString which does the same thing, but then (a) it won't have access to private methods so the public API surface gets more polluted with stuff the user maybe shouldn't call themselves, and (b) it won't show up in the right place in generated API docs and (c) it won't show up in the expected place in type autocompletion.
Kotlin has both static methods (or rather companion objects which are an equivalent), and also top level free functions, and when writing it I find myself creating static methods a lot more often for the above reasons.
I probably shouldn't have worded it quite the way I did. Considering I praise Go's access modifiers. What I meant was the "old" way of having lots of them and explicitly having to write them out. I haven't tried Kotlin but it sounds nice.
What I like about Go is the simplicity. Everything inside a folder is a package/module and any method beginning with a capital letter is public while every method starting with a lowercase name is package/module only. Coming from a decade of C# it was such a nice thing.
I do work with a lot of Python where you don't have private methods. I mean, you can set up your corporate environment to "hide" _methods or whatever, but they are never turly private, and static methods are... well... they are basically just namedspaced top level functions.
Not going to disagree. It's the sandbox that we're playing in though (dealing with, HOORAY JAVA!) since it's a class at school.
Have to start somewhere, teach them better alternatives as they evolve. Not even going to broach the prototype-based programing stuff until he comfortably has the basics understood.
Edit: I don't GAF about downvotes, but I would at least expect a response about why. If you don't like the philosophy, give me some reasons. Don't like something else, tell me why. I'll happily debate anyone all day long
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
.NET can serve the same use cases as Java, it's not just for windows programming. It's actually getting really good.
NodeJS does nothing better than anyone. The only things I can think of that make node worth using is electron and react native, maybe Next but I'd much rather do SSR in a real programming language personally. I would never use node as a pure backend, there's just no reason to and JS is an F tier language. TS brings it up to like C but it's still just not good enough to compete.
I can't see any reason to choose node for typical backend programming and such unless your devs only know JS. Any other language is probably better suited.
I agree with lots of things in your reply. In an enterprise setting where you mostly don't care about size of deployed application, then Electron is a godsend, where you can deploy a 500MB "Hello, World!" desktop app written in HTML/CSS/JS/TS in an afternoon. I know all about the bloat, but 99% of enterprise users don't care. A good web programmer can pump out very slick desktop apps incredibly quickly using Electron.
> I can't see any reason to choose node for typical backend programming and such unless your devs only know JS.
This is the primary explanation when I see NodeJS backends in enterprise. Mostly, those projects only have medium to low skill "web devs" (sorry, I cringe when I write that term).
".NET can serve the same use cases as Java, it's not just for windows programming. It's actually getting really good."
Last time I tried NET was 15 years ago, so I have no first hand knowledge anymore, but I do read regular complaints, that cross compiling to Linux(or developing there) comes still with major hurdles at times?
Nah, DotNET is amazing these days. At the risk of starting a holy war, it is neck-and-neck with Java, and I say that as a Java fanboi. I think it is good to have healthy competition between languages (and ecosystems), like C++ and Rust (and a little bit Zig) or GCC and Clang or Java and DotNet or Python and Ruby or NodeJS and Deno. Plenty of people are compiling and deploying to Linux after DotNetCore went open source. Plus, you can use JetBrains Rider, which is a cross-platform IDE for C#, from the makers of IntelliJ.
.NET is amazing and keeps getting better. JetBrains is killing it with their IDEs and add-ons.
Currently running nearly a dozen different services written in .NET running on Alpine in K8S.
Started transitioning most of my code to .NET Core/Standard when they first came out. Sadly, I still have to deal with some ASP.NET MVC code that was written before and requires .NET Framework
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.
> 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
See I missed that context :D
Installation readmes are an interesting example – they shouldn’t exist. Put that effort in an install script instead.
If you want me to mechanically follow some steps, perhaps with a decision tree attached … computers are really good at that!
The install script may not have all the context it needs to be installed. In the long run it is better to teach the user how your software works in plain english.
Even in projects with an install script, for example pmbootstrap, the install script also needs a tutorial.
In my experience, projects with minimal documentation and an install script will have the the install script fail halfway through because it assumed something about my system that isn't true, or it will do something incredibly insecure like requesting su and then curl | bash
> They’re more like academic papers (peer-to-peer communication of new discoveries)
This made me laugh because I frequently see HN comments on arxiv papers claiming things like the authors are trying to show off with their math rather than the math just being an effective communication tool. Honestly, if anything, papers are written to too broad of an audience and we get these 10 page papers that could be communicated in 3. I'm unsure if this has been a good change. (Yes, I read the whole comment)
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
> Most tutorials are not for non-developers, they’re for other developers who are also in the ecosystem.
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.
Entirely 100% true. I can count on one hand the times I've said "wow, this documentation was written by someone who cared". Threejs is a good example here, but even then it is subject to API rot and needless reference chasing.
Examples are often the best way to do documentation, sadly.
I've been leaning on test suites more and more for this. It's almost like a test suite should contain comprehensive tutorials. You know the API is good (hopefully) because if it isn't, the CI/CD pipeline wouldn't have let the release through.
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.
> Beginners have to be nurtured through lots of context that builds up slowly.
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.
I find that a lot of project homepages (or GitHub README.md these days) are riding high on "if you're reading this, you already know what this is for" energy.
What I would give for people to approach documentation in a more empathetic way; tell me what something is for, what problem it solves vs other competing solutions such as X or Y, whether it's still the best solution or in maintenance mode because another tool has become dominant.
Give me the tools to construct my own pros and cons matrix, without assuming that I'm an expert. Put five minutes into asking yourself "what questions are people likely to have, even if they aren't sure exactly what to ask" and write that down.
I'll never understand how someone can spend months or years of free time building something, but then actively sabotage it by not making it easy for people to realize that they've found what they are looking for.
It's also really valuable to keep perspective on the different kinds of documentation. https://diataxis.fr/ is a really solid starting point for anyone aspiring to create better docs.
This issue with READMEs in particular has driven me nuts for the decade I've been doing ROS related robotics stuff. So many repos where the only surface clue (i.e. before diving into the code) of what it does is your interpretation of its name.
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.)
I echo this sentiment. Whilst I completely understand that developers are doing this in their own time and largely for no other reason than it being a labour of love, it would really help lower the barrier to entry.
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.
What I really really want to read in a README is *why* did you build this? The "rationale" section of a README is almost always the most interesting part.
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.
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 was the most fun I'd ever had in a game, but it was also instructive. The battles were famously difficult and required a ton of coordination and strategy, and even a small mistake could get everyone killed. So our policy was that everyone in the raid had to sign onto our Teamspeak server, which was basically an audio-only Zoom call where my appointed officers and I could give orders and dictate strategy.
I very quickly learned an important lesson in communication: assume the worst. Surprisingly (to me at the time), most people who don't understand what you're saying won't stop you to tell you they didn't understand. And so I came to live by two rules:
1. If it's worth saying once, it's worth repeating. Assume people are only half listening, that they're distracted, that they're not paying attention.
2. Don't assume people know what you know. In fact, while talking, keep a second thread running where you explicitly ask yourself, "What am I saying that my listener might not know?" Then explain it.
The more I followed these rules, the better we did on our raids.
But even long after I stopped playing WoW, both of these rules have been helpful. Especially the second one, which helps overcome the curse of knowledge -- the phenomenon that occurs when a person who has specialized knowledge incorrectly assumes that others share in that knowledge.
Thinking about the curse of knowledge when communicating basically becomes second nature after a while. And then it becomes obvious when you observe other communicators who don't care about the curse of knowledge. They confidently launch into stories using obscure terminology and acronyms that nobody understands, without a care in the world for their listeners' understanding, they don't notice at all that nobody understands.
I remember being in a raid guild. The guild leader was this random 18 year old kid. I remember noting that this kid was expertly herding cats, many of whom were much older professionals, with absolutely zero direct authority, across multiple timezones, and getting them to not only agreeably distribute valuable loot, but also coordinate them through intricate boss dances and more intricate event scheduling. I thought it was a real shame that this wasn't direct evidence that he should be hired into a people management role immediately.
One of the things I've tried to teach people I've mentored over the past few decades is the principle of "Sharing is better than assuming." If you know something, share it with other people. Don't assume that they know something. If they do know, and you tell them, then you've only really confirmed what they already knew. If they don't know whatever it is you've helped them immensely and made whatever it is much more accessible.
Occasionally people will complain that you're being verbose and adding detail that they didn't need but in those cases you can usually just say "oh, that's just in case a [junior|manager|customer] sees it." People don't mind if you flatter them that the explanation was for other people.
It applies as much to development as it does to investment reporting, people management, delivery management, etc,
I have encountered a number of people who exhibit startling hostility at being told something they were already aware of. While I cannot currently recall a specific example, I strongly suspect I have previously felt this way myself.
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.
You would be if it's a tutorial on audio codecs and your tutorial starts with connecting the power cable to the computer, clicking 'log in', and don't forget to breathe!
> One of the things I've tried to teach people I've mentored over the past few decades is the principle of "Sharing is better than assuming." If you know something, share it with other people.
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.
Most tutorials aren’t for non-developers. They’re not for developers, either. They’re a bunch of prose I want to skip, and then I finally get to the steps I’m really looking for, but the author left one out, or assumed some weird development environment or IDE I’m not using, and I have to give up and go back to Google again.
The problem is that writing is hard, because it’s for people outside of your head, while you’re inside of it. As toddlers we learn that our senses aren’t immediately accessible to other people, but many of us never master the art of remembering that knowledge and experience inside our heads isn’t available to you, the reader, until we write it down.
Oh, and maybe if folks thought “cookbook” instead of “tutorial” when they’re writing, the result might be organized better for the rest of us to use, and less likely to become useless after the next point release.
When writing documentation, you need to establish a baseline of required knowledge and skills for your audience. You can choose any level, but deviating too far above or below that baseline will inevitably frustrate some readers.
When this happens, you can either make excuses or focus on solutions. Problems can be difficult, but with modern tools like AI systems, Google, or even books, it has never been easier to overcome them. If you don’t know what a Shoobababoo is or why you should use the quagmire instead of the hoobastank, you can look it up. Ideally, documentation would contain every answer with minimal need for external knowledge transfer, but the world doesn’t owe you that convenience.
> you need to establish a baseline of required knowledge and skills for your audience
So many guides for setting up like... "control system simulation" or "industrial automation compliance test-bench" start with "double click the exe and press next".
Baseline for expected knowledge for the user of the guide is SOOOO important.
I write stuff for our internal teams and it's usually for sensitive systems where you can cause a lot of problems if you make a mistake. I will often start the doc by saying "This assumes you know how to use x, y, and z. If not, then you probably shouldn't be doing this." We limit access already, but some of these could be used in a DR scenario by someone who is not super-familiar with the product. I purposefully will not explain certain things because if you can't figure those out, then you shouldn't be doing these steps.
This is primarily the reason why I stopped writing books and started making tutorial websites. There are so many interactive tools like <abbr> 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 yet most content is just these lazy walls of text. Event OP here uses footnotes that just scroll to the bottom of the page adding very expensive context switch for the reader rather than take advantage of the web browser capabilities like hover or modal pop ups.
Thank you. That is indeed quite extreme - I could use an article progress bar, footnote pop-ups (maybe, link back into article might be enough). Definitely not doing my own window manager. I'll try and read the rest of the design page with fresh eyes, maybe I'll learn something else.
I guess many tutorials are not made for absolute beginners and they have assumed you have learnt the basics before jumping into their topic. For example, if you never learn programming and set up an ide before, it has no way you can learn OpenGL as your first tutorial, and all the syntax and commands will look alienated.
And you can't write every document with an assumption that the reader knows nothing. Each document would end up the size of a phone book if you explained every single piece of technology used and provided tutorials for them.
Knowing where to jump in your stack is a tricky question, though.
OpenGL is not so bad because the API is quite stable. WebGL in particular is great because there's literally zero setup you need to do for executing it.
Integrating with Linux/Windows display surfaces is disgusting however. KMSDRM is way, way better than the nightmare that is X11 and Wayland.
My recent experience with getting an app deployed from Gitlab to a kubernetes cluster on DigitalOcean was exactly like this. There were like 3 or 4 different third-party technologies I was expected to set up with absolutely no explanation of what problem they're solving, and there was a bunch of steps where I had to supply names or paths as command-line arguments with no guidance on what these values should contain (is it arbitrary? Does it need to match something else?)
Mind you, I have relatively good Docker experience (wrote Dockerfiles, have a pretty extensive Docker-Compose - based home server with ~15 services) so I'm not new to containers at all. But man, the documentation for all these tools was worse than useless.
Personally, my main problem when learning new things is that, once an ecosystem has matured to a certain point, there's a baseline of knowledge that everyone inside that ecosystem has. In anything I read about it, this knowledge is assumed, and if I search for it, all the old articles that talk about it are either no longer available or just wrong, because that baseline knowledge gradually evolved as the tech matured, unnoticeably to the people inside the ecosystem.
This is an area where I find LLMs to be extremely valuable, as they often still contain that knowledge and can explain it to me in a way that makes sense.
I tend to write overly-long tutorials [0]. They are usually aimed at developers that reflect my own capabilities, but about a decade ago (in experience, but not tech). I write about relatively specific, advanced topics, aimed at folks with a baseline level of understanding.
I use a lot of well-tested code samples.
Writing for true newcomers, is very difficult, as there’s a lot of context-building.
My code documentation[1], on the other hand, is written for folks at my level (I basically write documentation that I want to read).
So many tutorials will just assume everybody's system, workflow, tooling, etc. are exactly the same as theirs. How many tutorials start with just "brew install"? It wouldn't take much time at all to say "You can use Homebrew to install this - here is a link to install Homebrew for macOS and Linux"
I don't see why there's an expectation that a "non-developer" should be able to understand documentation or tutorials written for beginners. It's a specialized field with technical jargon. There's a reasonable expectation that the person reading your tutorial is at least marginally competent. Beginner doesn't necessarily mean "non-developer." It could as well mean "new to this stack/technique/idea." I know this was written in good fun, but the implications that you shouldn't need some baseline competence to work through a tutorial is just wrong-headed. It benefits the reader to run into roadblocks and work through them. That's how you learn.
I call it "Kindergarten speak". People at the highest level of technical expertise sometimes have it, where they can patiently, and in understandable terms, explain to the most junior (but interested) party so the stuff sticks.
Others, while extremely nice and helpful, just don't "get" that their advanced jargon or, in my workplace, advanced mathematical language/notation, however elegant for themselves, is a huge hindrance for those not as versed in the art.
So if I, personally, say someone can explain something in kindergarten speak, that's the highest compliment. The more advanced lingo/notation stuff can come later, once the explainee has the big picture.
This is obvious for us who believe in and spend time on writing good documentation, but there are a surprising amount of devs out there who don't. "The code speaks for itself" people. Never understood them (literally) it's like some cult from the middle ages.
> How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner
Such Jargon! What's a developer? some kind of person who takes my fujifilm and gives me photos? And why do I care if someone is not such a person. Tutorial? what is this stuff do I need to sit in a small classroom? How do I read some college students sitting bored in a classroom?
This 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 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!
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.
I had to install vcpkg yesterday for the first time. Well, actually, I ran into a problem last week that could have been solved by installing vcpkg. I also happened to read a comment here on hacker news recently that mentioned vcpkg (but I didn't know what it was).
The problem was that 'cargo install cargo-show' wanted access to an OpenSSL installation (under Windows). The long error spew did mention vcpkg once or twice so I googled it and got very confused by the readme.
So I tried to install OpenSSL without vcpkg. That worked ('winget install openssl') but 'cargo install cargo-show' still didn't. Perhaps I had set up some environment variables wrong.
Yesterday, I finally figured out how to install vcpkg and it was indeed very simple, despite its readme. 'cargo install cargo-show' still didn't work -- it couldn't find openssl installed with the right "triplet" even though it was clearly installed in a way that should work for all 64-bit x86 Windows.
Setting OPENSSL_DIR and then running 'cargo install cargo-show' worked perfectly.
Apparently, there are different ways the directory structure for a vcpkg installed package can look and the vcpkg/openssl gave me one and the build script for one of the dependencies of cargo-show expected another.
Very, very confusing.
I think you can get away with just using 'winget install cmake' and then invoking cmake with the right command line to make it play nice with vcpkg (and that command line is listed in several places). I haven't tried it, though.
'vcpkg integrate install' sets up some sort of secret integration with Visual Studio -- maybe vcpkg learns where VS libraries and binaries (compilers/linkers) are hidden and maybe Visual Studio learns how to invoke vcpkg.
If you run it, it will also tell you to how to integrate more explicitly with cmake:
$ vcpkg integrate install
Applied user-wide integration for this vcpkg root.
CMake projects should use: "-DCMAKE_TOOLCHAIN_FILE=/workspaces/vcpkg/scripts/buildsystems/vcpkg.cmake"
The main advantage of cmake is it's slightly easier to use than autoconf so long as you stick to the path. Do not attempt to leave the path. Also the path is poorly signposted.
You never need to use everything a language provides. You find the parts useful to you or your team and use all of them.
I was a C++ developer for a decade and knew a fair amount of the C++13 spec but never needed to use even half of it in production. I've been a Java developer for years and don't know 10% of the standard library there. That doesn't make either language poorly designed by itself.
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
When I started with programming I didn't have issues like this at all. Most problems that I've faced where of the kind that when you compile or build that it didn't work and you have to spend hours going down the rabbit hole of dependency hell.
This article begs a more important question, is the burden of understanding the article / tutorial on the reader or is the burden of making it understandable on the writter?
I think a reasonable amount of knowledge about the topic being discussed in the tutorial should be expected from the reader but this should also be communicated by the writer.
Funnily that's one of the first questions on my mind when I look at a new program or library. What was it written in or what platform for, what's the build system or requirements and what does it actually do. Quite often I decide to avoid a thing entirely when I can't figure this out after reading the main documents. Sometimes you can look at the repo tree and just know, but often not.
This should be the first sentence in the landing page or README IMO. Instead you get something that looks like marketing copy written by LLM fed on BS generator output. Many projects just seem to refuse to tell the prerequisites at all.
When I was at the head of the jailbroken iPhone ecosystem, I put together a tutorial for how to get an SSH daemon set up on their phones. I put a lot of effort into making it something that anyone could follow, step by step, and achieve the result, making sure to skip no steps, assume no knowledge, and with screenshots showing the interface.
I soon thereafter received an e-mail from someone saying that they had excitedly followed my tutorial and found it very easy to follow; but, they had now gotten to the end of the instructions, were staring at some text that said "mobile@iPhone ~$ " (or whatever the default bash prompt was; I do not remember) and they did not know how to proceed.
I had similar experiences over the years, and I had a realization at some point: if you provide someone detailed step-by-step instructions for how to find the dragon, part of the UI/UX of the tutorial should be that you don't actually feel comfortable following it if you should not be doing so: the difficulty of the path must scale with the goal.
This is similar to real-world affordances, FWIW: if a user should not be opening a panel unless they are ready to do maintenance, yes, don't go out of your way to make it hard to service without permanently damaging it (that's evil), but, maybe, screwing the panel shut is more appropriate than providing a pull tab, due to what the latter implies.
A lot of users find this annoying, because they think they want to do X, and they just need better step-by-step instructions... but, that's just not how the world works: a lot of times, what you need to do to do the task is, in fact, a basic knowledge of the entire system, sufficient that you will need a fraction of the instructions (if any).
On the other side it causes another problem, BTW: if you make instructions that anyone can follow--including people who probably aren't at the level where they should do so yet--you also end up with instructions that are more difficult to follow for the people who should be doing so, as they are extremely verbose and often narrow in their scope.
It also sets up perverse incentives to try to make the instructions even easier to follow, well past the level of easiness the task should actually be at, which, again, causes problems for the people you actually want following the tutorial: if you find yourself creating little docker containers to avoid saying "install a compiler"... no.
FWIW, I was one of your users - back when it seemed important to jailbreak my iPhone - and I appreciate the work you put into it. I'm guessing that it was pretty thankless, for the most part.
Brilliant to see something from you here - a long time ago, I was there as well using your products and making a mess of things with stuff like afc2add and iPhoneBrowser
I wonder if there's just a mismatch in what 'a beginner' means. Perhaps the tutorial is aimed at beginners _in this specific topic_ ? I have also read 'intro to x' tutorials and had to do a lot of wider reading, I just accept that's the cost of trying something outside my area of knowledge.
It is actually a fairly well known phenomenon, certainly in educational circles. Being aware of it when you are writing any form of documentation is a first step. But even then, it is very difficult to properly assess the knowledge entry level of your audience.
Having others read through your documentation and importantly work with your documentation is a good strategy.
One thing I can also highly recommend is simply start out with a list of assumed prerequisite knowledge in your intro. Specifically things like certain environments, frameworks, etc. Bonus points for not only listing those but also linking to the documentation for those.
Tutorial is effectively a list of written orders. Problem is that if orders are not written in a detailed and specific way, person on the other side can interpret it in wildly different way.
This has been, and still is, a huge issue for military. Whole battles has been lost because order from a general was too vague or too open to interpretation (General Lee has been infamous for issuing vague orders which screw him up on Gettysburg). Prussians has invented whole wargaming which effectively has been generals writing orders in one room and officers pushing model armies in another room and reporting back to general in writing.
LLM is very good at filtering who can ask a correct question - order LLM what to do. People who can express themselves and describe problem will always get more mileage from LLM than people who will just throw vague request on it.
Have a bunch of checkboxes at the top, one for each buzzword, each technology and all other things a 12 year old wouldn't be familiar with.
You check which you think to be familiar with and all other things unfold a short description with links to similar interactive documents.
Each section comes with 1-5 star rating for how well the reader understood your explanation.
Then you gather the data as the subjects suffer though the tutorial.
If people come from specific backgrounds further tailor the explanation for them.(Like babazoofoo for C++ developers.)
Let there be a browser extension or an API that checks (and hides) the familiar boxes for you.
I didn't say it was possible to make. It would be glorious to have. If you know all the tech involved the whole thing implodes into a one line code example.
This is a nice idea, but looking back at how not only documentation, but also UX in general has not improved the slightest over the last decades, it's fair to say the only way we'll ever get close to anything like this is by leveraging personal LLM assistants, unfortunately.
Back when I was teaching myself Spring circa 2015 there was this one guy called mkyong who literally just did Spring tutorials - his site's still online at mkyong.com[0] - and while I did occasionally use Baeldung and the Spring docs, it was ultimately mkyong's tutorials that got me where I needed to be. The Internet is full of these kind of unsung heroes who happen to be really good at spelling out how to do something so simply an idiot could follow it. You kind of take them for granted as you train yourself up!
But is this tutorial meant for a non developer to read? I would imagine a linguistic psychology tutorial would have the same effect on a dev written by an expert.
Code samples. This is what’s missing most of the time. Even if you encounter esoteric jargon, if they give a few examples, it’s pretty easy to decipher. Even big companies like Google give code examples in multiple languages.
You are a beginner for a short time. Once you get your bearings you will beg for more resources beyond a beginner tutorial.
A serious framework, language or any other tool geared towards production, has to be supported by docs, tutorials and (where possible) a community of people actually deploying this stuff, possibly at scale.
I wonder if we'll see another post next year when OP realizes there's virtually no content for the Shoobahooba Snarfus ecosystem beyond some 'get started' guides.
If you have the right mindset and consciously seek to progress past it, yes.
I can recall seeing people spend years on concepts in a way where I really couldn't rule out the possibility of dedicated trolling. I remember one who would repeatedly ask about fixing problems with code examples using various advanced (at the time) graphics APIs while clearly missing several fundamentals about writing code in the language. And who also seemingly refused, the entire time, to adopt the proper spelling of "variable", despite it being corrected by multiple people in every discussion.
This is spot on, and can apply to anyone branching out into a new area. I will add this concrete piece of advice that can simplify things:
Don't ask the user to install tools or use ones that are not core to the topic. I still have a bad taste in my mouth from the 2 Scoops of Django tutorial after getting stuck installing VirtualBox, Chef, and Vagrant. The solution was to just not use them, because they don't have anything to do with Python, Django, or making a web server.
I could say the same thing about me "non-legal person" trying to read any contract, terms of service or a license document. Many people tend to make fun of the developers speaking a different language, without realizing, that they do the same in their respective field.
I think clear communication is important, but you can't expect anybody to write tutorials aimed for every audience. Learning is hard and it takes time to navigate through all the buzzwords and terms, but that's what learning something new requires.
I don't get it. I learnt to program from tutorials in the early 2000s. I guess at some point in my education I also learnt how to look stuff up. It turns out that was the real skill all along, I guess. So the question is why do people find looking stuff up so difficult? Can you imagine how long every tutorial would be if it started from the bottom? "If you want to make an apple, you must first invent the universe."
We devs are really good at answering two out of three questions:
1. How? This is the tutorial. It might be really helpful, for specifically what is being taught.
2. What? This is the reference documentation. It's often the most usable and complete resource.
3. Why? This is the context. It can only be learned by getting familiar with the environment. This journey is where we devs grow our metaphorical (and sometimes literal) neckbeards.
---
We could stand to pay a lot more attention to question #3. The contexts we have surrounded ourselves with are messy, conflicted, incompatible, and surprising. Some particularly savvy devs have made incredibly powerful tools to help clean up this mess, yet somehow those tools are some of the least noob-friendly software we have! How did we get here? Is there any way out?
I think the most uninviting part of our environment is also the most familiar: the shell. There are a lot of pokey bits that we really don't need anymore: escape sequences, suspend, environment variables, etc. What would happen if we took a serious look at starting from scratch? Could we do better than a REPL?
It's pretty incredible that after all these years, no one has actually made a real competitive alternative to the shell, and I have a theory for how we got here. The GUI model was created by corporations for proprietary software. We call them "applications", because they are supposed to cater to a specific predetermined use case, which is precisely what makes them inferior to shell utilities. This development model isn't limited to GUI either: apps have taken over the entire development scene.
I think if we really started fresh, we could revolutionize modern software to be more compatible, flexible, and malleable than any application could ever be. That's what a shell is already, which is why we devs never want to leave it behind.
Right now I am a tech writer and the curse of knowledge is hard to break for many people. I've gotten a lot of docs from devs that are obviously just reminders for themselves of what they already know. I've had to flesh out docs that just stop halfway through a procedure.
Please just admit that writing docs is hard. Because it is. Just because there is a lot of writing going on in college doesn't mean you learn how to do technical writing, academic writing is very different.
Go to the support team and ask them what questions are they sick to death of having to deal with (hint: its usually something you would think is pretty easy) and rewrite the doc to handle it. Then watch what happens to the support questions, if that disappears you did it right.
This has been a very informative and entertaining evening for me. I loved reading the comments. Also thanks for all the guestbook posts, they bring me great joy. May your Snarfus boop correctly forevermore. Devs are great.
The hidden files >_<. The classic "edit config.yml" step with no idea where the file should be. Special bonus for RKE2 would used to not even mention you had to create a folder to put the config file in because their install script does not do it for you.
But a part which is not mentioned in this blurb is locality of information. A good example would be traefik documentation where every part of the doc is written like you've already read all of it. Usually with not even a link between the different parts mentioning each other so don't expect something like a table of values where an option is mentioned.
"But you should learn all of it if you want to use it". Sorry but nope. Most people using your documentation will be of 2 types:
- they want to check what your software can do and will just try to get something running fast. So you need a good "get started" and some "how-tos" showing what it can do
- something is burning in production, they need a solution fast and it seems the problem is your piece of software which they don't know. You may want a guide on how to debug your thing. At least you want relevant information to be fast to get and easily googable.
As 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.
But you are starting at a level that assumes you are no longer a math beginner but rather a beginner in this particular area. If you were reading a high school algebra textbook, you shouldn’t have the same issue.
It's people sharing with others of equivalent skill. Use an LLM to adjust to your skill level. The times I write this it's to document something that worked. There's no guarantee it's what will work for you. You're supposed to translate it. So it's not really written for you.
On the flip side, it's taken me a long time to break my skimming habits and read slowly when I'm a novice in a new area. Especially with math or software engineering, it's often necessary to stop at each word I don't understand, unpack it, and gradually build a scaffolding for myself. This is very slow, but it pays dividends extremely quickly.
As a rule of thumb, it seems like skimming is useful if one already have a good familiarity with a subject and the content is slotting into an existing mental framework. However, when that's not the case, skimming gives me the feeling that I've learned something without much real progress.
I 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 hoobastank without a major gLibc upgrade. I got shamrock talking after compiling the compatibility shim for single-threaded pintafore and migrating from Debian to Fedora 75bit, but then the fistifunk socket closed! A few more hours troubleshooting and eventually figured out the root cause: The Snarfus node's DNS resolver was down. Turned it back on and everything worked perfectly.
I would bemoan the effectiveness of the advertising on me, but it’s just nice to see somewhat traditional advertisement styles working in the age of 5 second ads.
Wait really?? I also wound up migrating to Fedora 75bit for basically the same reason (TopHat doesn't even support hoobastank). But then I couldn't find `file` in the specified directory. I have
`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.
It was moved to a new path so you have to create symlinks in both locations to the new path under /usr/lib/newlib1.2/newfile.so otherwise, You can download a script that will make that for you but it will only work if you have all the dependencies for that script installed and their version numbers match the ones that the script owner had when he wrote the script.
So sorry about that. I should have mentioned the DNS resolver as a potential issue because it’s always DNS. Terrible oversight on my part, probably because I am not a developer.
One of my first policies: Every time we have a new hire, the first thing we do is have them go through our onboarding documentation and ask them to make corrections, improvements, and add clarifying notes.
Sounds like you may not be ready to read this tutorial just yet. Maybe get more experience in the terminal, and read docs on specific languages (elixir has good ones, for instance) or take a hands-on course (like Codecademy Javascript, etc).
Then, once you have more experience, you can go back to that tutorial and try reading it with more polished eyes.
What you've posted is the equivalent of me taking a new interest in cooking but applying to culinary school. If I haven't cooked in a real (production, high volume) kitchen, it's all gonna be Greek, overwhelming, and turn me off.
Unfortunately, the curse continues: follow up with how the text gradually coalesces as understanding grows. Realize how much easier it is after completion. Forget what "don't know what one doesn't know" felt like.
At least the beginner perspective captured enthusiasm, empathy (an alternative error condition for a path to a hidden file), and the request for feedback.
I wrote about this a while back [1] because most documentation is just plain bad. At best it's a reiteration of what is obvious and at worst it doesn't exist. Far too often it says too little of the bigger picture and too much of oddly specific edge case details. If I can't come to your project from 0 knowledge about your project and get it running without tearing my hair out, the docs failed.
Also there are some popular ways of explaining things that don't do the job (your experience is maybe different). For example: try to learn very basics of object oriented programming. The tutorial will inevitably have examples like "Class Bicycle" or "Class Car". These are out of programming context and never helped me to understand how to benefit from OOP in programming.
Another example is git tutorials. Having used git for years it feels so simple. In the very beginning it wasn't and those maps with circles and arrows didn't help.
A lot of kids who learn programming are motivated by a desire to make video games, and everyone already knows what a car is, so such class hierarchies are a good way to teach the concept.
On HN it's trendy to bash OOP and inheritance but it's a bubble; contempt born of familiarity. Real world codebases all use it extensively, including new codebases, and they use it because it's often a reasonable point in the design space for modeling problems. It's not perfect but the alternatives all have major issues of their own.
Obviously once a budding developer realizes that he can't find a job writing game engines and 'graduates' to writing DB driven web apps, the objects and class hierarchies he finds will be representing much more abstract concepts. But by then he'll understand what those concepts are, having mastered them in a less abstract concept space.
We did something similar with 'prod' code reviews. We started including a couple of the more junior folks in a pre-release review that was mandated. Intent was to say fine, id tech debt, or pull the andon cord if something was missed that would impact prod. What came out of it were their questions - which almost always was translated into an ask for documentation for that bit of code. The secondary bonus was they learned the questions that would be asked of the people who were merging.
"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...
This hits home, and not even relegated to software. My partner decided to learn to ride a motorcycle during the pandemic. I’ve been riding in some form or another for more than half my life. In the first minutes of attempting to explain the procedures, I immediately realized there were years of involuntary movements and coordination I failed to articulate because it wasn’t a part of my mental model of the process.
Needless to say she signed up for a professional course, got the license, and we’ve travelled nearly 10,000 miles together since!
Why be so snarky?
Documentation is there for users, it should assume that the user has the necessary background. If the user doesn't it is his responsibility to read up on the relevant background.
Pushing the burden of education on every single developer writing a tutorial is absurd. It makes the documentation unreadable to the people who need it the most and wastes time and effort. This style of documentation is totally fine.
Education is your own responsibility, do not push it on others.
I usually go over my guides and tutorials and try to remove jargon when possible.
However, I also try to clearify the target audience.
When I write a tutorial about storing files on S3 with the AWS SDK for Node.js, I won't start by explaining what JavaScript is.
Still, if I write something that has a reasonable chance that it is read by many programming beginners, I tend to add a link to FreeCodeCamp courses that help the readers to get the minimal education to follow my piece.
I’m not doing this either but: ideally tutorials should work on a very well defined environment (clean install, VPS with X setting, application deploy at version X with plugins at versions A, B, C)
Then they should have a unit test. And a passing status. The problem with most tutorials is that they simply rot. So many times they tell you to do a command with a flag that doesn’t exist, install two incompatible packages or click a button that isn’t there.
This level of extreme hyperbole is silly and not in any way helpful. Try analyzing an actual tutorial (which will only be an analysis of that one--quality varies a lot).
I'm a developer and I read most tutorials like this.
Pretty much every "thing" I come across today uses some kind of dependency that I have little, or no, experience with. Unfortunately, even though the "thing" might be interesting, the fact that I'll have to spend 4-16 hours futzing with things that are completely new to me to get somewhere is often what turns me away.
One minor tip that I think can have a big impact: whenever writing down something to run on the command line (e.g. for documentation or other kind of sharing), always use the --full-version of the flags (instead of the short -f version). The extra information it conveys is worth a lot. If someone gets tired of typing it, it's easy to find the short version.
> Just for shits and giggles, you can de-sham the chronostatiomatrix by running —()()(]]asdg a=-do —cd go cd stay —sususudododo baby shark—][] but that’s optional.
Except in most real cases you're following the tutorial for, where it is both mandatory and non-obvious it's not been done.
Something like the mock one here I think is really more often largely intended as a sort of logbook entry, a note to self, 'how I did x' (in case it breaks, I need to do it again, update it), it isn't really 'for me', the other.
It's always a problem that you forget what you use to not know.
When I first started writing some internal docs/tutorials at work, I was new to Linux. So I generally took the time to include tangents into explaining fairly basic Linux concepts, because they were new to me. They were rough edges I had to get past so I wanted to help others do the same.
Five years and a shit load of Linux experience later, I don't do that anymore. That stuff has become so second nature to me that it just doesn't even occur to me anymore. And I just don't have the damn time. If I had to stop to explain what cat or sudo or | mean in every doc I write I wouldn't have time to get anything done.
> 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
Regardless of the level a tutorial is given at, there is information that is missing. A well written tutorial knows its audience and contains all the information for that audience.
Sure, I will grant that someone who doesn't know what a computer is shouldn't be expected to follow a tutorial to install PostgreSQL on a headless linux server with proper security protocols in place.
The issue is more that it's extremely easy to assume someone understands what "primitive file operations" are necessary to accomplish a goal, and fail to describe what it is the user actually has to do.
Just because you understand how to navigate a file structure doesn't necessarily mean you have the domain knowledge necessary to make leaps that are frequently present in tutorials.
> and fail to describe what it is the user actually has to do.
How is "go to a folder and copy file content" is not such a description?
> doesn't necessarily mean you have the domain knowledge necessary to make leaps that are frequently present in tutorials.
Again, rather than speaking generically, how does this post demonstrate it? What leap is present in "this tutorial" that an average reader would not have the knowledge to make?
You’ve assume your beginner knows that In the Terminal meand open the Terminal application, knows how to open the Terminal, knows that the Terminal uses typed commands, knows that typed commands are followed by Enter, and knows that the text following Terminal are the typed commands to be entered.
The non-garbling threw me off (it wasn't jabbernocks), so assumed some passing familiarity. But even granting that, you can add a few minutes and a few google searches to your complexity budget.
If anyone has an open source project and wants a review of their README and docs, please get in touch. I enjoy providing this type of feedback, and I think every project can benefit from it.
I once was asked to teach a class in beginning C++ that was put in the paper as beginning programming in C++. Some of the students really weren’t ready for the class they found themselves in.
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.
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.
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.
I prefer to think that updating the documentation isn’t fixing the root issue, and that the working systems are their own documentation if explained properly, so document in such a way that they can’t become outdated, when feasible.
Makes me want to revisit my (started, but not posted) screenshots and videos of trying to install matrix / element following the random directions / docs.
it might be in library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam.file.
On Fedora you'll find it in:
library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam.file.d/boop_settings.cfg
I went to library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope but I don't seem to have a /never/ folder at all.
i started frequenting hackernews because i knew that tutorials written by developers would start making sense if i just kept trying to read them. it worked!! took a few years though.
A paper in a cancer journal and a Web MD blog can discuss the same disease, and both will seem like a foreign language to the wrong audience.
And now we have LLMs, most of the "trade words" and jargon can easily be translated into a kindergarten reading level if that's the reader's background.
OPs argument is flawed. Documentation is not there to teach you from scratch. Its there to describe a projects intended behaviour under normal conditions. Often times people will cry about lacking context and expect you to basically use it for them. I would heavily recommend against that as you will end up as unpayed and burned out tech support...
Honestly, I'd say this doesn't even just apply to beginners to software development. It's applicable to even experienced developers who are new to a language or concept.
I've been teaching myself Rust in the past week and I've definitely noticed that, when I hit an error, a lot of library documentation assumes more depth of knowledge than I have right now. Say I want to know how to use a specific function and, beyond the quickstart, the docs are just a reference that keeps talking about Traits. I'm sure it'll click eventually, but right now, I just need to know how to call the function and fix the error I have!
Side note: I've rediscovered why Stack Overflow is so helpful as some of the answers there have helped me understand what's happening with different issues I run into!
"Gee Rick, uh, I d-d-don't know if this tutorial is for real, I mean there's a bunch of random nonsense words and other stuff. I mean, is 'backside Snarfus stagnator' even a real thing?"
"Shut up Morty, you just don't unders-*buuurp*-tand what it takes to be a software engineer."
"Are you sure? What's a 'hoob-tunnel' and how does it get clogged with 'gramelions?' That just sounds like an improvised line from that sci-fi cartoon show..."
You are right but the fact that it will be harder to distinguish between human written and AI written text means that we will be looking for signs that indicate a human written text and will tend to prefer humanly mistakes over AI perfect tutorial.
Whenever my team (cybersecurity) is about to send a global email or post, I wander around non technical teams to get 3 or 4 people to read it and explain me what it means.
Not once I got it right on first attempt. The final version was very different from the first one.
This is similar to the web page that was proposed to serve as the message people would read in case of a critical disaster of our systems.
The first version was with Vue, Tailwindcss and whatnot and I opened it on an old phone. Everything was everywhere, with drawers all over the place. I said that I would not approve anything beyond https://motherfuckingwebsite.com/ because I need it to work on a tomagoshi.
The version we have now is beautiful in its ugliness and clarity. It opens on a smart watch (well I don't know that actually :))
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 whole discussion in itself. If I remember correctly, the availability of training material for a technology already has slightly impacted more niche corners of the tech world.
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.
I like the term acerbic brevity! Generally though, I'd say concise and precise is exactly what I want in my docs, especially if I have to read hundreds of pages.
There's a fine line to walk for it to stay understandable though.
Academic papers sometimes take brevity to the extreme due to page limits and (frankly) bad writers, so much so that crucial parts are missing or ambiguous or where papers consist solely of formulas with little context.
Personally I draw the line where I need start writing down stuff in order to understand the following paragraphs. That's tedious.
However I encountered the other extreme too and it's similarly unbearable: full on conversational English in an overly friendly tone with everything explained at length and sometimes repeated. It gets old really quick and takes longer to get to what I need. Fine for a hobby project, but if I need it for work I don't want to spend time on that.
Taking an idea, and converting it into code is a lot of work. Taking that same idea and then taking the code and turning the both into words that can communicate the original idea is just another complex task.
I'd wager that the dopamine hit of getting stuff working has worn off and most people are writing doco when they're exhausted from their recent work.
Apparently it was so much more effort than she was willing to expend that she ended up just randomly banging on the keyboard ... and yet many here are treating this as some sort of serious criticism.
Reminds me of an acronym that defines this sort of behaviour: COIK.
What is COIK? well everyone knows what COIK is, no need to bother explaining.
COIK is 'Clear Only If Known.' Did you really have to ask me about such a simple thing? Now run along.
____
There is so much assumed knowledge that writing guides becomes a matter of how simple you have to go, before you start insulting the reader's intelligence. (A computer is a magic box that goes DING!)
If you writing a guide, do you explain what a terminal is and where to find it? Or do you presume they know what it is and start sharing command lines? Is setting a minimum knowledge bar acceptable or are you showing your bias?
> 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 from a completely different area of expertise. They shouldn't have to know what snarfus are, or how to fisterfunk the shamrock portal. In that case yes, let's mock the developer for completely missing the mark with a 6 paragraph long joke.
A beginner developer, however, is someone completely different. This is a person who will eventually have to juggle snarfus, and as unfortunate as it may be, even need to fisterfunk the shamrock portal. It is partially on them to put some effort into figuring out what fisterfunking is, and how it applies to the portal. If they are particularly good, after figuring out what those things are, they may even volunteer to update the documentation as to make it easier for the next beginner developer to understand it instead of replying with a 6 paragraph long joke about it.
FWIW, I submitted it as "non-developer" but a moderator seems to have changed it to "beginner developer."
The author is a non-technical blogger, and she probably has to navigate lots of technical guides in order to fiddle with her website or CSS. I think a more relevant discussion would be about making website publishing easier for everyday people, or about the lack of documentation written for that particular demographic. But HN took it in a different direction, which is fine.
> FWIW, I submitted it as "non-developer" but a moderator seems to have changed it to "beginner developer."
The author is a non-technical blogger, and she probably has to navigate lots of technical guides in order to fiddle with her website or CSS. I think a more relevant discussion would be about making website publishing easier for everyday people, or about the lack of documentation written for that particular demographic. But HN took it in a different direction, which is fine.
That makes sense, thanks for clarifying. That's why made sure to point out the difference to avoid confusion. I think folks, including myself have been on all 3 sides of the situation: as a new developer who is supposed to learn confusing terminology, non-developer who is thrown a bunch of jargon to look at from a completely different domain that's not their responsibility, and the developer who write stuff and then wondered why other can't comprehend the "easy" tutorial.
Checking out the homepage, Annie says her job is "content & documentation things", but also mentions CSS as a hobby, so I think it's a safe assumption this is the "non-professional hobby developer" niche which I think we'll see continue to grow.
It's a hard balance to get right. I've seen "install this tool" sort of tutorials which literally introduce the concept of opening a terminal and pressing Cmd+V and others which expect cron and Make knowledge as very basic table stakes. It's a wide variety!
I think if we're writing for an audience which will contain some amount of beginners or non-developers, it's maybe ~2min of effort to add a little collapsable (straight from Claude if you want) going into what exactly we mean by "cd into ~/.snarfus, creating it if it doesn't exist"
I donno. I remember being 13 trying to install Debian on my dad's old laptop. Any nuggets of knowledge helped.
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 your priority, in this case partial docs is better than no docs at all. But if your target is beginner developpers, imo you should consider them as non-developpers, as you correctly descibed them.
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/
SDZ should have been Heaven for me, but even as a teenager, I just couldn't get past the omnipresent enthousiasm and the smileys at the end of each sentence :)
:)
Guess I've always been grumpy.
Oh and yeah it's probably been enshittified nowadays, everything has. Wouldn't surprise me if they partnered with Ecole 42 to inundate the job market with programmers without degrees and drive the salaries down even more.
By changing "non-developer" to "developer" (moving "beginner" from the end to the beginning doesn't really change the length). That's quite an intrusive change, it seems to me.
How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner
How I, a beginner developer, read the tutorial you, a developer, wrote for me
My apologies, SoKamil, for cutting off the ending in the comparison. I wanted to highlight the difference and figured the first part is where the difference was. As in, they are still a non-developer and shouldn't have to learn all the details so it doesn't matter if they are just a regular non-developer a beginner non-developer.
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.
Also a lot of beginners skipped a lot of (cultural?) foundational knowledge. A basic understanding of filesystem, network, and os commands would go a long way for communication efficiency. Instead, they’re cargo-culting.
There really is a huge gap between a programmer and being capable at using a computer. I work in the data space and while im good enough for my own needs with Python and grew up in the 90s with MS-DOS and Windows 3.1/95, the second i have to use something that is build by and for programmers i too end up feeling like the blog post describes.
The difference is merely how this thing works vs how this thing is used. And the glue factor between the two is ops.
Between the developer and the user, there should be the maintainer role. Someone that took a software and make it run on a specific system. That requires familiarity with the system internal and build systems.
This is why packages managers like in linux distributions are a great solution. A working solution is often just a command away. App stores could be good too, if not for the gatekeeping effects.
> 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.
For me the issue is some people expect everything to be simple/easy to do without any prior knowledge and then claiming it is not really hard but you are gatekeeping and only if you could explain it easier they would definitely grasp it instantly.
Also, it really depends on what the tutorial is about.
There's a difference between a tutorial on how to set up a wordpress on a shared hosting or how to add aditional debugging capability to kernel application core switching routines by patching the linux kernel.
In the first example, "unzip it" might need an additional explanation on how to do it in the command line... in the second,.. well... if you can't even unzip a file without the tutorial, you won't be able to use the software anyway.
In the end, lots of people who try to accomplish their goals writing some code don't see themselves as beginner developers but non-developers.
They just want to accomplish some well-defined and scoped task that happens to require some coding, but they have no interest, at least for now, on becoming developers.
Just confirming, I've seen that the title between the post and link are inconsistent incase there's any confusion.
While I agree, the difference is significant, and it is often the case that a a decent tutorial/blog post on a technology is rarely tailored to non developers
I do think there's a kernel of truth in this for with educational content written by developers. I think many developers underestimate the attention and care that's necessary to write high quality education material. Not to say they shouldn't, it's a valuable skill for everyone to develop but it doesn't always come naturally.
I think one part of it is, in writing the content sometimes someone who is inexperienced in writing, might be writing something with dual roles in mind. They may be venting their frustrations with learning the technology, selling their experience and accomplishments (to any potential employers who may be reading it, which is where some name dropping might be coming in) and using the format of a tutorial as a vehicle to do so. They may also just not have a clear objective of what they want to write in mind and they just want to share some information and they initially wrote a tutorial and veered off on to something else.
If you're someone who is reading something like this, it can actually be annoying or confusing if you went into the tutorial expecting one thing which doesn't end up being there. For a beginner even more so, as you lack the domain knowledge to know if you need to disregard these tangents or skip forward, if you're more experience it feel like someone is wasting your time by telling you they were going to explain X Y Z then it ends up being some rant passing as a half baked tutorial. That said I rather this than AI slop, but reading it can be equally annoying if it feels like the author doesn't respect your time in the way AI slop feels like there's an expectation your time reading it is worth less than the time the author would spent writing it.
The issue here for the reader is usually the content is inconsistent with their expectations, and for the author they possible communicated that poorly.
Yes if the author has mistakenly assumed an article not written for them were written for them, well yes that's on the author. But taking what they say at face value or even the title used at the post I think there is a point of value to take away from this for those writing anything ranging from education material to a post mortem.
Know your objective, the key information your communicating, has the way you've written effectively communicated that to your intended audience? Cull things that detract from this. And of course there's nothing wrong with unstructured forms of writing, they can be really fun, but they are the last thing someone wants to read when they are in the middle of trying to fix a technical issue they don't entirely understand. That can largely be avoided by with a better title, or avoiding insinuating the post is something it's not.
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 users won't have it. (even watch them pretend to know what they're supposed to do when they don't really).
If the user achieves what they need with minimal stress/guesswork/ambiguity, the docs pass. If not, note every single place they fail, address each one, and repeat with a new user.
I've used FAANG docs that don't come close to passing the above criteria.
I've been incredibly grateful my org set this high bar. Especially when using docs for critical tech I only use from time to time (where I forget lots of it). Saves meetings, support inquiries, and video calls, because the user can self-serve.
I seem to have this problem a lot with Apple’s docs. So much of it is like
You need to do something besides repeat the name in the definition.This is just one example of how metrics can distort things, of course. Someone in management said "We want 100% documentation coverage of every method," so the staff dutifully wasted everyone's time by writing "setDefaultOptions: sets the default options". It's the kind of thing an LLM could have done better, and if you know my opinion of LLM's, you'll know that's damning with faint praise.
My own bete noire here is MSDN. It's full of overloads like "Foo(string parameter, FooOptions options) - actually useful documentation. Foo(string parameter) - does Foo with default options." But to find out what the default options actually are, you have to find another page, probably the FooOptions constructor. I wanted the default options to be mentioned on the "Foo(string parameter)" page, and they so rarely are. (A few pages are better, thankfully).
And then there is Microsoft's annoying habit of creating APIs which return the information you actually need . . . nested three levels deep inside a bunch of their own custom data structures.
I've basically resigned myself to "it makes sense in Redmond somehow, even if it makes no sense to me."
Microsoft's APIs basically shove all the implementation details onto the API user. This is, of course, abysmal API design, but "tasteful design" (in any sense) and "Microsoft" have never been in the same building. But it does make sense. And it also tells you how to interact with Microsoft APIs: the same way you interact with the hardware details that assembly languages export to the user, namely through a wrapper. (But, taste is difficult to find; that wrapper might have imbibed some Microsoft "design" by virtue of being exposed to too much Microsoft.)
Rant: if you want antialiased text, you need to use Direct2D. Direct2D is one of those APIs that waste developer's lives. You have to allocate your own framebuffer, for crying out loud. And then, you have to reallocate it if it ever disappears for some reason, and the docs don't tell you when this might happen (hot swap a video card? change monitor resolution? User moves window to a monitor with a different video card?).
I found this out developing a cross-platform UI library, https://github.com/eightbrains/uitk, leading to my above conclusion that the only proper way to relate to the Microsoft API is through some layer.
> But to find out what the default options actually are, you have to find another page, probably the FooOptions constructor. I wanted the default options to be mentioned on the "Foo(string parameter)" page, and they so rarely are.
It's better for maintenance (of the documentation) if the default options are only described in one place. (If the defaults change in a new version, this ensures the documentation doesn't have inconsistent, wrong descriptions. The analogous reasoning, applied to the code, is probably part of why the FooOptions class exists in the first place, after all.) But they should do you the courtesy of linking there.
This is only a problem if you write it twice. Instead you can write it once and display it twice.
Hell, I even do this on my github.io website that uses markdown. You can just write some text in one document and read it in another.
We're programmers, so we should be lazy. It's about being the right lazy. You can be lazy by putting of a task today that takes more effort tomorrow or you can be lazy by doing a task today that takes less work than it would take to do tomorrow. Most people choose the former and wonder why they have so much work. In programming if you're doing redundant work then you're probably being the first type of lazy
In code documentation doesn't support such thing. And documentation outside of code suffers from rot.
Some varieties of in-code documentation do support links, e.g. XmlDoc which is the de facto standard for documenting C# code (and therefore the most relevant to my comments about MSDN because I was referring specifially to the .NET API documentation) has multiple ways of embedding links in your in-code documentation comments: https://learn.microsoft.com/en-us/dotnet/csharp/language-ref...
MSDN even uses those, a lot. But not enough. I wish that every time they had a "Foo(string parameter) - uses the default FooOptions" it was a link to the documentation section where the default FooOptions are listed. But usually you're left to find the default FooOptions yourself, which means 5-10 minutes of digging through docs (1-2 minutes if you're lucky) that I could have spent writing or reviewing code instead. That adds up.
We are talking about MSDN not some source files. Even if those pages are generated from in-code documentation that generation step can use whatever transclusion mechanisms Microsoft wants to add.
But that could be linked up rather than have you fumble through to find them.
In some fairness, the page existing at all is half the battle. I'm glad the canvas exists for the paint to eventually, maybe, one day arrive.
Related to this is the omitting of units. I encountered something like this in the Android SDK (years ago, dunno if it’s still like this).
Cool. Sets the font size in what? Points? Pixels? Device-independent pixels? Which of the 12 different types of measurement Android supports is used here? I can’t remember exactly what it turned out to be, but I know it wasn’t the unit I expect for fonts (points).In similar cases (maybe not exactly here), I suspect the author also didn't know and didn't care to look it up and just wanted to tick the box that it's now documented.
This is why I rage against the crowd that promotes "self documenting code". There's no such thing, even if you should strive to make your code as readable as possible. But if there's a way to misinterpret it then you can bet many people will.
The biggest problem is that this ends up creating so much extra work. An extra 2 seconds from the dev could save hundreds or even thousands of people hours of work. I can't tell you how many hours I've spent chasing stupid shit like your example. I don't know a single programmer who hasn't.
I just don't understand why everyone's frustration with documentation (or lack of) doesn't make obvious the importance of good documentation. Every single one of us has experienced the wasted time and effort that results from the lack of documentation or from low quality docs. Every single one of us has also reaped the benefits of good documentation and seen how much faster it makes us. How does anyone end up convincing themselves that documentation is a waste of time? It feels insane
This kind of bad documentation is actually way more common in teams that require doc comments for all code, which are then promptly auto-generated by the IDE and never filled with actually useful information.
Self documenting code in this case would mean using a type that encodes the unit - which would have the additional benefit that the compiler or other tools can now check correct usage.
You're misinterpreting
Requiring docs isn't the cause of the problem. It's the lack of enforcing quality. The difference is that you're looking at the metric and seeing Goodharts Law in action while there's nothing preventing you from going beyond the metric. That's the real issue is that metrics only take you so far. No metric can be perfectly aligned so it's up to the people who are evaluating the metrics to determine if the letter of the law is being followed or the spirit of it is. If you do the latter then yeah, maybe some functions will be left without docs but you also won't hasn't those tautological docs either. If you only care about the letter of the law then you should expect the laziest bullshit as Goodharts Law always wins out.
Stop reading too much into metrics. Metrics are only guides
Code can show you HOW something is done. Only documentation can explain WHY it is done that way.
That's more about API design than about documentation though, as with a proper function name/using value objects/something else, you already know what the correct value to pass is.
It's a widespread issue though, where the API designer doesn't clearly communicate either what the thing does and/or what the thing needs.
If you don't need the docs then you don't need them, but sometimes we all need a "hey bro, I know you're a little lost so I'm going to break down what's happening in plain English". At a certain point you just don't have the entire code base in your head all the time and you need a reminder on what exactly the Flargle team does to all the Nargs.
This is why I'm sad that hungarian notation has gained into such a bad reputation. Sure, you can overdo it, but a `duration_ms` or a `response.size_bytes` or a `max_memory_mb`, or an `overhead_ns` is so much easier to use.
Better yet would be unit-aware types. Then instead of
duration_ms = 1000
you can have
duration = 1s // or duration = Seconds(1) in deficient languages
and it's either a compile error or the type system enforces the correct conversion.
As for the bad rap of hungarian notation, it's mostly from people using it to encode something that is already clear from the types. "fDuration" helps no one over just "duration".
AVMetadataKeySpace
A structure that defines a metadata key space.
source: https://developer.apple.com/documentation/avfoundation/avmet...
That’s just a C enum interfaced in Swift. You can’t instantiate it, and it has no methods or any kind of functionality. It’s effective a list of numbers.
What are you expecting the documentation to say here? It will make more sense when you find where it’s used.
Edit: First link on the bottom explains exactly what it’s used for. https://developer.apple.com/documentation/avfoundation/retri...
struct AVMetadataKeySpace - a unique unit representing each of the metadata key spaces supported by AVFoundation.
? Did you read the link? It’s used to query collections of keys grouped by the KeySpace categories, instead of a single item per key. Makes sense to me.
There’s plenty of other poorly documented Apple APIs (io_surface), but this isn’t one of them.
> It’s used to query collections of keys grouped by the KeySpace categories
Sounds like something that should be mentioned in the opening sentence of https://developer.apple.com/documentation/avfoundation/avmet...
The struct is only named on the link you provided, not documented. So thanks for showing the absolute irony of it not being greatly documented, allowing people to misinterpret what it means.
Because it’s a boring enum in C, auto translated to a swift struct.
And if you’re reading the documentation because you do development, then you would already know that the header files are installed on your computer and you can trivially verify that there is nothing to document because it’s just a query key.
Enums get documented everywhere else. If nothing else, you need the range of options!
Going off to read the header file means it isn't documented.
Not quite what you're talking about but this Apple doc page has always amused me: https://developer.apple.com/documentation/contacts/cnlabelco...
I have to assume that there exists some language where that relationship is described in one word, but it hurts my English-oriented brain.
There are indeed languages that don't have the word "cousin" -- or "uncle" or "aunt".
And conversely, there are languages with different words for "father's sister" and "mother's sister", and for male vs female cousins, etc.
And we don't even have to get exotic for that. My language, Danish, is just a run-of-the-mill Germanic language and those terms are "faster", "moster", "fætter", and "kusine".
Some of the East Asian languages are crazy regarding terms for family members. It's like learning foreign words for plants: I just give up. I will not even attempt to learn them.
There are also languages where the relative age difference changes how you address a relative. Like if your father is older or younger than their sibling, the way your address that uncle or aunt changes. There is another way you address them if they are the oldest or youngest uncle/aunt. Similar but slightly different on the mothers side.
But I would bet that those variable labels are never translated into other languages.
Presumably those enums are used to select localized labels and you need all these cases to cover unique words / phrases that exist in the supported languages for specific familiar relations.
Or with Xcode, go to fargler settings click on narg screen. Took a year just to figure out most setting screens
> with Xcode, go to fargler settings click on narg screen
I hate how this looks "accessible" to people in theory, but in reality finding those screens is more like playing a hidden object game.
Also, I hate how those things keep changing around in all kinds of software, but especially Apple. Somebody probably thinks "yeah maybe we should move the Fargler settings from the Narg to the Birp screen", and makes dozens of internet "documentation" (and sometimes their own!) obsolete.
Apple documentation reminds me of an argument I got in with an elementary school teacher over a textbook… it went on for weeks
> A prepositional phrase is a phrase with a preposition in it.
> A preposition is a word in a prepositional phrase.
One problem I remember from (briefly, fortunately) dealing with Apple APIs is wondering incessantly why every API (I was looking at) started with NS. Admittedly these days any AI would tell me it stands for Next Step. But if you are creating a new thing with a quirk like this please explain it once, in a place that's easy for the student to find.
The more useful answer is:
a) it needs namespaces
b) but giving people namespaces is unironically bad because it's what lead to "enterprise development" style APIs like C# where everything is named System.DataStructures.Collections.Arrays.Lists.ArrayList, as if giving something a longer name makes it more professional.
c) so instead two letters means a system framework and three letters means a user framework
I quite like a terse but consistent conventions myself. I remember finally being able to quiet the tedious part of my brain that couldn't get past the NS conundrum when I finally came up with the NextStep thing as a reasonable theory.
In other words, my only complaint is that this Apple convention is not more easily discoverable. Or perhaps that the expert author of the book I was reading (this was back in the day) didn't feel the need to share it with his readers.
Triangle theTriangle = new Triangle()
Lives rent free in my brain.
I want a linter against this. I have a hatred for those kinds of docs, they take up screen space, its worse than nothing.
The issue here is that people are treating reference materials as tutorials intended to cover your exact concern at the moment. You are expected to know what a narg is and what flargling means. In more real terms, the documentation for screen savers https://developer.apple.com/documentation/screensaver?langua... won't explain what a view is, what subclassing is, or what a Rect is. Those are required knowledge to consume the documentation and it's not a documentation failure that this is true.
No, you missed the point. The problem isn't "narg" or "flargling" - those are just random stand-ins for normal words. Instead the problem is that the description says nothing that isn't already said by the symbol name. Whether or now you know what "narg" and "flargling" mean, a documentation page for Nargflargler that just describes it as "Flargles the narg" provides zero additional information to you.
then how would you descirbe a nargfargler?
dont say.. boop?!
God I hate this so much when I google some unknown word and it's just: "Nargflargler: When someone narg flargles something"
> Do not speak to them, certainly do not help, just watch.
Sounds simple, right?
I ran usability tests at a past company and have seen people who were incapable of blurting out explanations, pointing at the screen, even audibly grunting or whining to themselves when the participant made an incorrect guess about what something meant. One even grabbed the mouse.
Having a neutral moderator can help as it allows the people who made the UI/docs to stay on mute or on the other side of one-way mirror.
But I'd still suggest learning the "just watch" technique. If you master that and wish to take the next step, look up "think-aloud protocol".
I mean, if the test user can't figure it out at all, how is the rest of the UI/documentation supposed to get evaluated?
Great question!
If you let someone flounder on one task indefinitely then you don't learn anything about subsequent tasks. But if you correct them too quickly you won't uncover the other approaches they would have tried to complete the task. Most research plans define cutoffs such as:
1. Participant expresses extreme frustration or gives up
2. A couple minutes have elapsed from the first failed attempt
3. Participant unsuccessfully attempts three distinct approaches
If the test reaches one of your cutoffs then the interface/docs have failed the task and the moderator can skip to the next task or question. Sometimes they'll also offer to show the participant the expected solution or explanation.
Exactly. You want to learn as much as possible from each study. Explaining too soon reduces amount learned, as does ending the study early because a small hint wasn't provided to get to the next step.
> You can also record it to show them later, but for various reasons it doesn't resonate quite as strongly when it's not live.
Yeah, because it's wasting my time having to watch people who literally have never heard of something as basic as keyboard shortcuts. It's fine if I actually have the time to explain to some Gen Z kid how Ctrl+X/C/V works, but being forced to sit around and watch someone with that level of non-understanding of how a computer works when I got a full backlog of shit to do is just agonizing.
With a video recording, I can at least go forward and see where they actually have problems with stuff that is in my influence and skip over the utterly boring moments that are just wasting my already limited time.
Before I saw your response I removed this sentence from my post as I realized it was not central to my main point. However, I still agree with it and am happy to explain why.
> wasting my time having to watch people who literally have never heard of something as basic as keyboard shortcuts
First it depends on whether the audience for your product includes people who do not know keyboard shortcuts. If that's not your target audience then the rest of the test may not be valid anyway.
Otherwise, there is utility in forcing yourself to watch your users struggle with your product. The best product developers/owners I know have a bottomless appetite for observing people use their product, even if doing so means deferring the rest of their "full backlog of shit". Perhaps they're less efficient in the short term at churning out lines of code, but the understanding and empathy they develop makes them significantly more effective in the long term.
It's like how expert athletes often watch videos of themselves or competitors (when applicable) to understand the nuances of their play - once you understand something very deeply the small things start to matter more, until they dominate the game.
If you are a master of UI/UX and you are observing a user doesn't go through the paths you've created its an opportunity - you might be able to learn something that would make your approach more successful across a host of different users that up to this point you clearly are not winning the game against.
If you take an antagonistic approach and curse the idiot for making you watch you have not even put on a jersey yet.
This is our documentation workflow as well: Write it, and then have someone less or not experienced with the system execute the runbook. Also, encourage everyone to work on refining and improving the docs, because after 5 years with a system, I will have blind spots someone less experienced can point out.
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.
A good first exercise for new hires! (And I say that as having been both a new hire who's updated the documentation after trying to execute it, and as someone who's guided a new hire when the documentation proved inadequate.)
Any kind of documentation has a target audience. Your test is very valuable if and only if the target audience is a total beginner. Of course it's still very hard to write good documentation even if you have identified your target, but having someone totally illiterate on the subject matter review your documentation is as useful as if I'd have to review a PhD thesis in quantum physics. It just doesn't make sense (trust me :).
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.
For most public documentation, you don't get to pick your audience. You think you'll have people with certain experience, but then it turns out you're wrong. Usually a lot of the time. And even when you're not wrong, having the steps essentially from scratch listed out reduces the number of times people get stuck, because they think about things they may have missed.
I cannot tell you how many times I've had to go through 30 hyperlinked pages of fluff explaining universal basic concepts before finding the five sentences I actually needed (buried in five different places).
And just as many where people explain in detail exactly how to do foo with bar without explaining why I would want to do foo in the first place and what a bar even is.
Way too much documentation is like this. Then again, lots of times asking coworkers about an existing system or a new ticket that's not detailed properly ends up with them saying 30 pages of fluff to me before I can get to the nugget
This really is one of those things that AI can improve, and already improves today.
As much as I'm not an AI booster, it has helped a lot when I hit a wall with poorly done documentation where the related bits I need are scattered all over and even a text search isn't helping me
I was gonna write something similar. Know the audience. I've also come to the conclusion that "total beginners" (and certainly "minimal expertisers") didn't nowhere to read the docs anyway so it didn't matter.
In other words, people who are used to reading docs can read (good) docs just fine.
Yes, of course, good docs are a must. They are critical to success. But not all docs have to explain how to use a right-mouse button.
Perhaps in addition to a description of the expected audience, it might be an idea to list some assumptions made about the reader? e.g. has installed software previously, confident with bash commands, &c
I almost systematically use BLUF (Bottom Line Up-front) when I write docs, I think I'll make TABLUF a thing from now on (Target Audience and Bottom Line Upfront) :)
The experts are likely to be skimming and interpolating your doc, so they'll get through it but you won't know why. You won't know if your doc works, or if it even addresses the subject matter. This is also true of academic papers.
My mom taught CS in the 1980s, and told her students on day one: "Computers are stupid, they will only do exactly what you tell them to do, not what you want them to do." Program code is, in a sense, a tutorial for an utter beginner. The benefit of coding is that you can do the "beginner test" over and over without wasting anybody's time, so you know that the computer will get through it. But an expert (including yourself) might read that code and never see that it does or doesn't work.
It's crazy how bad most onboarding docs are for corporate teams. I think it's a great first look the culture and how much of a hassle the role will be. The last three teams I've joined have been brutal with how little was documented or how out of date the docs that did exist are. I've had to spend up to two weeks tracking people down to find out what access group I need for our logs, deploy pipeline, etc. and I end up writing up a new doc that's good for its point in time, immediately becomes out of date when someone adds a new system or access group but doesn't document it anywhere. The one team I was on previously that got me everything I needed in about two days was great, but it's sad that this isn't the norm. Everywhere else has been pretty hostile to getting set up, and the poor onboarding experience has been a preview of the developer experience. My current role is standing up a new devex team which I'm hoping turns the tide here.
It's not very crazy to me. Most corporate teams are overrun with feature creep that "is very simple" (i.e. it takes 3x as long as estimated, because the codebase is a mixture of overengineered spaghetti for that one customer with edge-case requirements and legacy, combined with tests that are meant to be run in a jenkins job which takes 4h to complete).
Then, the engineers are expected to write the docs in between these tickets, and doc is seen as something "to be done within 30 minutes" - of course the docs will be comically (or tragically, depending on your perspective) bad.
Most people have 0 idea on how to write good docs, so in 30 minutes, they write stream-of-consciousness docs and return back to the ticket hell.
Most places I've been could have been upgraded with stream of consciousness. It's not surprising that they aren't all perfect, and the one place that was done to a very high standard was properly overdone, but at most places whatever counts as onboarding docs either doesn't exist, is essentially unusable, or directs me to legacy things that on day one I don't know enough to not bother with
if you're writing a new doc to "fix" this situation, you're commiting three crimes: 1. all that old documentation still exists, misleading and confusing people. you've now made the problem n+1, 2. there's no strategy to keep your new document from turning into an old, stale & out-of-date document for the next person, 3. you've addressed the wrong problem (nothing's documented!) and feel like you're superior to all the jerks who came before you.
>> My current role is standing up a new devex team which I'm hoping turns the tide here.
I'd love to know what you're doing different that can help with this problem. Writing more, new documentation is unlikely to be it.
You're right that it's not a complete solution. The overall process on this team aren't good (we never do a retrospective, ever) and I don't get to decide how we solve #2 and #3. The best I can do is bring things up to date, keep it up to date as I run into new info or we add new systems to access, and hope that future new hires are smart enough to check created and last modified dates on documents to find the most recent one.
Sometimes I wonder if it's a respect or control issue. I once worked in a non-technical position that interfaced with a complex order management system. We were given zero access to documentation and had to rely on trial-and-error and the reverse-engineered model held in the head of one specific supervisor. I'm almost certain that certain errors that appeared over and over were caused by us temporarily clearing previous ones incorrectly. This was especially frustrating because we were 2nd shift, so dealing with those errors could mean the difference between getting home that night or getting home the next morning. It was hard to tell where along the line between, "They're not sophisticated enough to make use of them," and, "We don't want our processes leaking," we fell, according to the higher ups.
My mother worked in engineering back in the late 80s until early 2000s and always told me about people who didn't document things because they wanted to be un-fireable. I didn't believe her or take it too seriously until some of these more recent teams, but I think it is a lot more common than it should be.
A technical writer's first task is to start the document that onboards the next technical writer.
Reading through bad setup docs is 10x more stressful when they are part of new employee onboarding.
I’ve always advocated for new employees first contributions to be fixing problems they had in these setup materials. They are coming in with fresh eyes and no context so they are the best possible reviewer
My first ever software developer job, I was hired with basically no knowledge or experience to learn (I was very lucky). I knew MS-DOS command line pretty well from my childhood, but hadn't ever used POSIX. I was given a macbook air and some docs to follow.
Trying to follow the docs, supplementing with a lot of googling, I somehow managed to remove the tar program from my system. This broke literally everything. Had to stop halfway through the multi-day process to do a clean reset and start over from scratch.
We called this the “receptionist” test decades ago at the small company I was at - after we though we were done we’d give it all to the receptionist and ask her to use it; and we’d hang our head in shame at everything we forgot and head back.
There’s a version for kids to show the details of how to program by literally interpreting steps. https://youtube.com/watch?v=n4rh2jD8OkY
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.
I am that guy. I will also say from experience: It does not pay. Never once has it been ack'ed in a year end review (which controls bonus, salary increase, and promotions). As soon as a manager sees you as "The Wiki Guy", they take you for granted. As I grow older and more cynical, my view on internal docs: (1) Write them for yourself. (2) Write them to make people go away when they ask you questions ("Did you search the Wiki?").
I had this issue during a job interview exercise. Their "follow these steps exactly" were simply broken. The root cause was that they were having people re-use the same shared remote amazon desktop system. Each candidate got their own home directory, but they wouldn't just reset the image between candidates. The person before me had used up 98% of the drive space. When I followed the 'step by step' guide, nothing worked, because it was out of drive space, but... I wasn't seeing 'out of drive space' messages directly - I was seeing their 'setup shell scripts' looking like they worked, but then nothing did.
I honestly thought this was some sort of trick exercise to see how I deal with broken processes, and I was writing fixes to their docs and shell scripts to deal with error states, and reported back to the person. I initially got a 'no, this isn't that sort of test. the docs work, just follow them'. After more back and forth, I got 'oh, I see that might be broken, yeah, just carry on'. I fixed what I could, made a couple commits back up, but was then told my commits needed more context, which I then added, and promptly never heard back from them again. Until... weeks later, HR reached out to say "we've gone with someone else". I recounted this story and got at least some semblance of feigned shock of 'that's not how any of this is supposed to go'. I'd kept some screenshots and emails, but they didn't care to go down that road.
tldr - Employers giving tests, please run through your own exercise processes now and then (or maybe even automate them with some smoke tests).
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. It didn't make sense, but it's what you had to do! So these guys tried to 'fix' it, and in doing so, broke it.
The whole support model was predicated on this idea that the 3rd level guys would write stuff that the 1st level guys would slavishly follow. It never worked.
You could probably fix this, to some extent, by adding a sidebar to the instructions that 1) acknowledges that the procedure doesn't seem to make any sense, and 2) points out why the seemingly obvious fixes won't work. That's usually immensely helpful to me as a reader, so I don't have to waste time wondering if I misunderstood the instructions or the author misunderstood the procedure.
Joel Spolsky famously wrote in the year 2000:
— <https://www.joelonsoftware.com/2000/04/26/designing-for-peop...>
That's it! :-)
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.
Problem is a lot of times silly instructions are silly because they are wrong. Like why did you turn left and try to drive through that river? Those instructions assumed a bridge was there but it washed away 10 years ago. A new bridge exists, you can see it, obviously take that one instead.
You can achieve a lot of this by creating a blank virtual machine with "just the operating system" as a starting point and stepping through your own instructions from there.
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.
I agree that testing from a vanilla machine is important.
But there's also that your language to the user doesn't necessarily say what you think it does. You can't read it from the position of someone new. Only someone new can.
And a set of commands to paste to CLI isn't the full extent of what we usually mean by documentation.
Yes, more of this!
I am a big fan of the "clone, F5" and it should run. If specific steps are required, I put that in a setup.ps1, and the details in the readme.md.
If the project has external requirements, I put a link to the repos, which should all be... "clone, F5"...
When I type F5, my terminal writes "~" but nothing happens, what did I miss?
In case you weren't attempting to make a point through irony, GP appears to be using "F5" informally as shorthand for "instruct your IDE to attempt to build and run the code". Presumably, that kind of documentation wouldn't normally literally say "F5" there unless a specific IDE had already been prescribed. The point was simply that the user shouldn't be required to do anything manual to set up the code, when starting from scratch, except perhaps to authorize the automated setup procedure.
Indeed, snapshots are an amazing friend for this.
Or let the Junior rewrite the docs while they're scratching their head, and push an update once they've figured it out.
I'm a senior designer who often contributes to front-end code when it's convenient for my client.
Fixing and updating the README when I join a new team and set up their dev environment is always extremely well-received.
If i'm gonna untangle something, i may as-well write some notes. If i'm writing notes on it already, i may as-well refine the grammar a bit and update the docs. It's really quite small effort compared to the main work of learning the system, so i don't quite get why so few people do it.
Wow, way to double down on “I really hate everyone who doesn’t have exactly my skill set and experience.”
I'm ... confused what you mean. If the junior is gonna untangle the docs anyway, why not make them directly update the parts that confused them once they're through it.
I apologize; I misunderstood. I thought you were making a “fend for yourself” argument; I was not associating “junior devs on the team making the docs, need to fix docs or make good ones”.
They're not necessarily prohibited from asking questions if they're stuck, though. But also search in the chat channels for similar issues.
Updating docs in source control also onboards folks to code review. It would be weird to update docs and get a hostile reception.
While nice to walk through with someone and conduct a usability study, just leave it better for the next person (who could be yourself, if you forget). That has happened before.
I think you are misreading the parent comment here.
I'm a Jr. sysadmin at a medium sized software company. Whenever I document workflows for our users, I have two colleagues of mine who have no connection to IT work through them and add the small gotchas they asked me to the docs.
It saved me a whole bunch of headaches for when other users get enrolled in these workflows.
I've been doing some cal/QC functions recently after years not touching it. Since I last did it I've forgotten some of the knowledge that is just assumed. The answers to my questions are documented, but not in a places that is accessible from the production side and has lived as community knowledge in production. I've been making a list and updating the documents to fill in some gaps.
Unfortunately some of the production people aren't comfortable enough pushing for changes in the documentation so some of my job now is to ask what they've noted and get it added.
I'll go against the grain and say that fumbling is how you learn. The easier it is to get to the end of the tutorial, the less you learn in the process. If you learn math from a bad book, you have to organize your own notes, to untangle the mess. If it's laid out all neat and clear like a straight highway, you never wrestle it out with the concepts and you don't learn.
That's something I came to accept as well - deeper understanding will only come from challenge. Unfortunately, there isn't always the opportunity to let people fail, and that opportunity is definitely not in a set of reference docs.
> and that opportunity is definitely not in a set of reference docs.
Okay, but GP is talking about tutorials, which are a completely different form of documentation.
I like to always provide a docker image which can be used to execute whatever solution I'm developing. Most of the time the docker image isn't even used, but it's an important exercise because I'm forced to run my solution on a fresh system, so the resulting docs will invariably be more complete, and it also documents the dependencies in a way you can easily verify.
This is basically the user testing approach as described in "Don't make me think" by Steve Krug. You can use it to test usability of your applications as well.
Don't speak to them or help them at all?
Suppose they get stuck on the first step in a multistep procedure. Do you just let them keep flailing on that step for however long they are available, so all that you learn from that entire session is that the first step needs rewriting? Or do you end the test and let them go, again learning nothing beyond that the documentation for the first step sucks?
Wouldn't it be better at that point to help them on to the next step and then continue on having them test the rest of the steps?
I am stuck in an organization for some personal reasons.
The first thing I noticed when I joined was the culture of "Please ask when something is not clear". After was given a quick overview in person.
You guess: almost everything is unclear. A mess. Need to ask a lot. Task descriptions, purpose, reasons, whys, wheres, what does this comment mean, why are these things contradict each other, and so on, and so on.
And except asking KG, usually the answer is: ask XY. Or KG.
People always busy, always in rush, give a condensed answer raising the same amount of new questions that it answers.
When KG is out, productivity slows down.
And all this beyond the usual in a meeting, out with customer, on holiday, sick, the children is sick, held up in a traffic jam, car broke down, need to finish project P so schedule something for next week, and all those kinds of common things making the relevant person unavailable when "something is not clear".
And beyond the forgetting 4 things of the 15 new info given by the time we are finished with the converstaion. No written trail to look back at.
When 3 person paint a complete picture then all above happen three times in a row, or in a never ending loop.
Productivity suffers, quality suffers, I will leave as soon as I can.
Positive things? Probably that the expectations are low. And they pay well. And by now I am irreplecable in a local subset I was hacking together (I do not call it work or development), not even KG can help others there! I will leave on my own terms (as usual, unluckily).
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 whole system. The situation is even worse on Android, where there are dozens of standard APIs to achieve the same functionality.
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)
As far as I recall, many libraries in the Java ecosystem, as well as the Android API, don't have the official tutorials or guides you're referring to. The JavaDoc and the Android API reference are often the only officially available resources.
So no, Those aren't just there to refresh developer's memory. In many cases, they are the only resource for learning the system from scratch.
About JDK Java docs:
This is a great phrase. I fully agree with your sentiment. To me, I never read Javadocs in HTML-only form. I always read them in an IDE, along with the library code in question. If anything is unclear from the Javadoc, then read the code (which immediately follows the Javadoc).I also occasionally fall back to the source when the documentation isn't comprehensive enough.
But as library users, we're generally not supposed to have to learn the system from its source, aren't we?
> Usually you look for code examples or a guide for learning how those work
... which in practice means, particularly for stuff that recently changed, that you go to StackOverflow only to find out that the majority of posts are horribly outdated and don't even compile any more.
The other side are code examples that technically work and show, say, the syntax on how to use a programming language's or framework's shiny new feature... but manage to dumb the code example down so far that one has a very hard time wrapping around one's head on how to use this feature in a real world application.
I was reading The Art of Unix Programming (E. Raymond) and one of the advices was that every library should come with a program. So even it’s a todo list kind, I think it’s quite nice to have.
I started a company to do exactly this a few years ago, and got to work with amazing companies testing their developer experience.
The problem is not the docs, it's Conway's law. One team designs the API, the other team designs the portal, and another team designs the SDK. The user has a holistic experience that cuts through each team.
That, and the docs are usually written first by the most technical person around, who has a hard time sharing the world view of a noob.
> 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
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.
I do think a lot of developer tutorials and documentation don't take into consideration that many people might not have a common understanding of terminology especially if the reader is coming across this problem or process for the first time.
So doing the basics of product design? :D Sounds like a good approach! Sadly user tests or other forms of iterating are often overlooked.
The golden rule: Plan -> Act -> Test -> Repeat
Fully agree. Good docs are essential for scaling a team beyond the first few hires. I always make a point of filling in all the gaps I had to gather myself during my onboarding, and ask the next hire to do the same (and carry it to the next hire, and the next) this helps keep the docs up to date with the relevant knowledge since it’s always being filtered through the lens of a brand new computer and a dev with minimal context.
People here are talking about it as if its merely a problem of wrong target audience when the problem is a lot of docs are straight up lies. The example setup steps and configuration in the front page itself fails. That's what makes me wish I could shoot someone or something.
Thoroughly agree. Where I come from it's called "shoulder surfing". It is really important to not help.
> If not, note every single place they fail, address each one, and repeat with a new user.
Might not this loop be invoking Goodhart's Law?
What is "address each one": are we just changing that document, or are we (also) changing something in the system that the document is about?
If no newbie has any problem following the document, is that still a good document for non-newbies?
If no newbie has any problem with the system that the document is about, are there any downsides?
I absolutely love this approach. It is in the spirit of https://1x.engineer/ and it should be applauded.
> 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
And if you have access to user experience researchers, go talk to them! They are experts in running this kind of scenario, and can help you avoid all the pitfalls that might bias your results
Totally. Something that I see a lot is software that tries to read a config file during startup that bails out (sometimes with no error message!) if the file doesn't exist. Or tries to write the config file into a directory that doesn't already exist.
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.
We do this in game development .
Watch someone play the game for the first time. Don’t interfere. See if they can figure out how to play.
Play testing is the most important part of game development. Indies who struggle to come up with concepts are really sleeping on this. If you run play tests well enough your roadmap will almost write itself. Players will do and ask for things that you would never dream of.
I think an intense culture of playtesting is why valve software puts out games so rarely. Their new strategy seems to be to keep a title semi-secret for years while a small army plays it full time. If Deadlock makes it to market, it is almost certainly going to be an acceptable game to most who are even remotely interested in the genre.
I wonder if we now have the tools to build unit tests for docs now; an LLM should be able to take on the persona of a beginner try to follow your doc. For bonus points use a dumber/older model that can’t have trained on your API.
Basically, ergonomic testing, but for your doc instead of your software.
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.
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/
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.
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.In the past (20 years ago), those tier 1 roles were a great feeder for the organization. Because that role touched so much, it meant everyone had a lot of perspective on the organization as a whole, and thought about support and maintenance while building new things.
It’s easy to say who cares and hire from the outside, but that organizational context and care for support is lost. People build whatever and throw it over the fence, which makes everything worse, imo. Those people also tend not to stick around, so they have no skin in the game and it’s hard to develop culture as people rotate in and out frequently.
There are always some people who will never learn, and these people are cheaper, but there are other hidden costs as you seek to optimize for low-skill workers.
I always write my own notes when setting up to "fill in the blanks" of the guide, then I create PR with them.
are you interested in giving a talk/presentation about this
this works great, if, they speak out their thoughts verbally, in real time.
> 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.
Ask the guinea pig (read: victim) also to think aloud.
LLMs have mostly eliminated the need for this. They are quite good at explaining things.
Correction: They are very good at writing seemingly-good explanations. The explanations may or may not be correct.
Correction: They are quite good for this: Easy beginner level stuff. For that specific thing, they are much MORE correct than they are wrong.
The status quo is a moving target. 6 months ago what you said would be fully correct. This is no longer the case, now you are only sometimes right and mostly wrong. It is getting better.
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.
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.
Without AI, it was really hard to get to understand some docs. Today if you don't use AI for these situations shrugs
Most cases it is not that docs author forgot users wont have same toolchains. Simply do not bother reducing config files to share just source code. Indirectly pushing users to make use of same tools.
Hopefully in 20 years no one will be going to check the source code of anything, and programming is elevated even more.
50 years is crazy amount of time, to stay this primitive. Tech shouldn't just evolve for end users.
Most tutorials are not for non-developers, they’re for other developers who are also in the ecosystem. They’re more like academic papers (peer-to-peer communication of new discoveries) than they are like a pop sci book or show meant for a general audience.
And that’s okay! Great even! As a fellow peer I benefit greatly from those tutorials. Sometimes even from my own notes published and forgotten years ago.
This is why courses and other structured learning materials exist. Beginners have to be nurtured through lots of context that builds up slowly. If every article had to start from scratch, we’d never get to anything interesting. By the time we got to the interesting bit after 30,000 words of preamble, you’d be long gone as a reader.
And the very next reader would complain that the 30,000 words were not enough introduction to the topic. They needed 40,000.
> 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.
Ah, the infamous public static void main(String[] args). Hopefully the next generation won’t need to learn all those concepts up front with the introduction of instance main methods in Java 25.
https://openjdk.org/jeps/512
I actually think the inscrutable Main method in java has some value. As a kid, I loved to know how things worked and always did things like read instruction manuals and read ahead in school textbooks. I wanted to know everything about anything, and I wanted to know how it worked from the bottom up.
The java main method taught me "This is abstraction, an important concept in programming. You won't always know how all the magic works all the time"
It taught that you have to deal with black boxes.
Also, I never saw it cause problems in CS101 classes, because the kids curious enough to want to know something their professor didn't explicitly talk about were usually the ones who would do fine at learning all the parts of it.
The kids who struggle with programming never seemed to have problems following "Just write your code here, you will learn more about it later"
He’s starting with Java? I wonder if that’s the right language to start with. What is he most interested in doing? Anyway thanks for nurturing the next generation.
I fully disagree with Java as a starting point and it was an interesting conversation with the teacher.
Apparently, "College Prep" courses more or less determine that Java is the language that they should use.
His teacher thought it was stupid as well, but sometimes your hands are tied. That's what the schools are using as a starting metric though.
He was apparently the only person in the class that said he wanted to do software engineering. Don't worry, he'll be a polyglot before he reaches college.
I learned Java in uni and think it's a fine language to start with. It's also been modernized a lot in the past decade, and if you really want a more modern language it's easy to transition to Kotlin.
I'd take Java over Python or JS any day. It wins on performance, it wins on type system, js is just a plain trash language not at all suited for general purpose programming (TS solves some problems but not all and it has its own problems) and python is fineish but it's slow and just kind of icky, I'd never do serious software development in python. It's fine for small scripts and notebooks and such, we learned python as part of our math classes while the programming classes focused primarily on Java. We also had a class on web development using JS, ML using Python and windows programming using C++ and C#.
I struggle to see any significantly better candidates for a first language than Java. Sure you could go with C but nobody really uses it any more outside of niches. C++ is out, too much stuff. I really like C#, it's my daily driver and I wouldn't mind it as a first language but I think Java is more approachable for beginners. Less confusing syntax to learn. I don't know Go but maybe that could be an alternative? Other than that I'm a bit out of options.
Java is a fairly simple language that's easy to learn and allows teaching a lot of important concepts that will be useful in other languages moving forward. That's a big thing I think, it's not meant to be the only language. The word polyglot is used some times, to me it just means programmer. I don't know any competent developers who only know one language. You end up learning multiple and I think Java is a good entry point.
C# is amazing. Decisions at the education level were made well before it went cross-platform though (FWIW, I've been using it since before v1.1).
Would be interesting in what confusing syntax you're referring to. I think one of the beauties of it is that it's additive. You can program plenty of simple stuff in it with conventional style code, but there's a lot of syntactic sugar available that makes things so easy when you need to start scaling things.
I agree, C# is my language of choice and I've been using it professionally for over 5 years. I use it for personal projects as well.
I'm referring to all the stuff C# has that Java doesn't. Async, ref/in/out keywords, extension methods, linq, lots of stuff. Maybe it's not a big deal, like I said I wouldn't really mind it. I just think Java is a bit simpler in this regard which is an advantage for beginners.
Some differences where I prefer java are checked exceptions and imports. C# usings are ambiguous, it can be difficult to figure out where things are coming from for code samples outside an IDE. And checked exceptions are just good IMO. I've never seen why people dislike them, having used Java and C# I think Java does it better. It's easy to miss exceptions in C#, I wish library developers could use checked exceptions to tell me which exceptions I should worry about.
Anyway both languages are great first languages and great general purpose languages. Highly recommend both.
Thanks for taking the time to respond. Ultimately though, most of those aren't required from the beginning, but the syntactic sugar, abstractions, and performance gains from them are amazing.
You probably already know, but I'll opine a little bit about extension methods. I use them a lot.
Entities > Repositories > Functionality. All split out.
- Entities (pretty much just gets and sets, nothing more than necessary).
- Repositories via extensions to determine where the data comes and goes from (some data comes from SQL, some from Redis, some from Postgres, doesn't matter since it's split out) and any particular queries you need for optimizing things.
- Functionality via more extensions without adding additional code to the entities.
Separation of purpose/use.
I may or may not have completely replaced our data layer in the middle of the height of our season with no interruption. Little bit passionate about this one.
Would you happen to have something like a github repo with examples of those repositories? I'd be interested in seeing that.
Personally I'm not a big fan of copious extensions. I use them some times but I'd describe my usage as sparingly.
I wish. It's on Github, but my hands are tied and I can't share them since it's someone else's property now (hooray for exits, I think).
It's mostly a thought process...
I have or need something (entity), lets get data about it (repository/extensions), we need to do something with this now (only extensions).
Lots of "static" and "this" involved, but the separation and eventual simplicity makes it worth the effort.
Edit: I tried going through some of them to anonymize some for examples, but it felt like treading in dangerous territory.
Java's a pretty good beginning programming language. Outside of the mystical incantation of `public static void main(String[] args) {` and what the difference between `new ArrayList` and `ArrayList.new()` is (I still don't know but I haven't really touched it since college), it's a good statically typed imperative language that you can throw objects and functional stuff into when it's time, isn't going to give you weird errors about indentation, has just enough pointers for you to learn how to avoid a `NullPointerException`, does things pretty "conventionally" (ie, there's not a lot in Java that doesn't also show up in other languages), and is easy to compile and run (when you're not using 3rd party libraries, which students in something like a Data Structures and Algorithms class aren't going to be using). Ideally you have another class teaching you another language too so you get the double bonus of learning what a language is and what a language isn't, and Python's good for that, but by itself Java's fine
> Outside of the mystical incantation of `public static void main(String[] args) {`
I don't think it's mystical. If you don't have an instance of the class yet, you need a starting point and static fills that void (lol. I'll show myself out)
My first programming class was Java. That was 8 years ago. Maybe the curriculum designers thought Java would be relevant for the workplace? The education system always lags several years behind industry trends.
My first programming was also Java. That was...27 years ago! That's some lag.
> 27 years ago!
Sometimes, I feel like I'm the only old guy on here. BASIC, VB6, .NET, and some Java along the way.
Too many new ones to list, although that might be a whole other problem in itself.
> Had to explain to him public, private, internal, and also static the other night.
Access modifiers are sort of a dying breed in a lot of places aren't they? We use Go, so we're obviously still using the two it comes with, but it's public vs module only and fairly intuitive. Every other language we have in production, doesn't make use of access modifiers. Similarily while static is a thing in Python, it's hard to see what advantages it brings compared to a free function if you're using a programming language that doesn't require you to have object instances to call non-static functions. Obviously access modifiers will stick around in a lot of organisations, but there will be plenty of jobs where you never have to work with them.
The way Go handles modules, is frankly one of the few language feature of any language I've ever worked with that I wish was in every language I work with. It's so easy to use and so hard to mess up. Ok, I guess it's not hard to mess it up, but it's not intuitive.
Access modifiers are useful, albeit not for beginners. They're most useful in statically typed languages with good tooling where they keep auto-generated API docs and autocompletions clean.
Static methods are useful for namespacing, e.g.
In some languages you can of course make a global free function called someThingFromString which does the same thing, but then (a) it won't have access to private methods so the public API surface gets more polluted with stuff the user maybe shouldn't call themselves, and (b) it won't show up in the right place in generated API docs and (c) it won't show up in the expected place in type autocompletion.Kotlin has both static methods (or rather companion objects which are an equivalent), and also top level free functions, and when writing it I find myself creating static methods a lot more often for the above reasons.
I probably shouldn't have worded it quite the way I did. Considering I praise Go's access modifiers. What I meant was the "old" way of having lots of them and explicitly having to write them out. I haven't tried Kotlin but it sounds nice.
What I like about Go is the simplicity. Everything inside a folder is a package/module and any method beginning with a capital letter is public while every method starting with a lowercase name is package/module only. Coming from a decade of C# it was such a nice thing.
I do work with a lot of Python where you don't have private methods. I mean, you can set up your corporate environment to "hide" _methods or whatever, but they are never turly private, and static methods are... well... they are basically just namedspaced top level functions.
Not going to disagree. It's the sandbox that we're playing in though (dealing with, HOORAY JAVA!) since it's a class at school.
Have to start somewhere, teach them better alternatives as they evolve. Not even going to broach the prototype-based programing stuff until he comfortably has the basics understood.
Edit: I don't GAF about downvotes, but I would at least expect a response about why. If you don't like the philosophy, give me some reasons. Don't like something else, tell me why. I'll happily debate anyone all day long
Maybe he and his teacher are caught in a loop ;)
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.
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
Some notes:
.NET can serve the same use cases as Java, it's not just for windows programming. It's actually getting really good.
NodeJS does nothing better than anyone. The only things I can think of that make node worth using is electron and react native, maybe Next but I'd much rather do SSR in a real programming language personally. I would never use node as a pure backend, there's just no reason to and JS is an F tier language. TS brings it up to like C but it's still just not good enough to compete.
I can't see any reason to choose node for typical backend programming and such unless your devs only know JS. Any other language is probably better suited.
I agree with lots of things in your reply. In an enterprise setting where you mostly don't care about size of deployed application, then Electron is a godsend, where you can deploy a 500MB "Hello, World!" desktop app written in HTML/CSS/JS/TS in an afternoon. I know all about the bloat, but 99% of enterprise users don't care. A good web programmer can pump out very slick desktop apps incredibly quickly using Electron.
This is the primary explanation when I see NodeJS backends in enterprise. Mostly, those projects only have medium to low skill "web devs" (sorry, I cringe when I write that term).".NET can serve the same use cases as Java, it's not just for windows programming. It's actually getting really good."
Last time I tried NET was 15 years ago, so I have no first hand knowledge anymore, but I do read regular complaints, that cross compiling to Linux(or developing there) comes still with major hurdles at times?
Nah, DotNET is amazing these days. At the risk of starting a holy war, it is neck-and-neck with Java, and I say that as a Java fanboi. I think it is good to have healthy competition between languages (and ecosystems), like C++ and Rust (and a little bit Zig) or GCC and Clang or Java and DotNet or Python and Ruby or NodeJS and Deno. Plenty of people are compiling and deploying to Linux after DotNetCore went open source. Plus, you can use JetBrains Rider, which is a cross-platform IDE for C#, from the makers of IntelliJ.
.NET is amazing and keeps getting better. JetBrains is killing it with their IDEs and add-ons.
Currently running nearly a dozen different services written in .NET running on Alpine in K8S.
Started transitioning most of my code to .NET Core/Standard when they first came out. Sadly, I still have to deal with some ASP.NET MVC code that was written before and requires .NET Framework
I concur with most of your thoughts, except that Java is never going away. I might wish that it would, but here we are.
Java doesn't have an internal modifier. Concepts like public, private and static exist in Python too.
"Most tutorials are not for non-developers"
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.
> "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"
tbf, that's not how I read the headline. The headline is: "How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner"
The author is a beginner, which puts them in the field - so the parent comment is valid no?
The headline has been edited, in its current shape I tend to agree to you.
> 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
See I missed that context :D
Installation readmes are an interesting example – they shouldn’t exist. Put that effort in an install script instead.
If you want me to mechanically follow some steps, perhaps with a decision tree attached … computers are really good at that!
The install script may not have all the context it needs to be installed. In the long run it is better to teach the user how your software works in plain english.
Even in projects with an install script, for example pmbootstrap, the install script also needs a tutorial.
In my experience, projects with minimal documentation and an install script will have the the install script fail halfway through because it assumed something about my system that isn't true, or it will do something incredibly insecure like requesting su and then curl | bash
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
> Most tutorials are not for non-developers, they’re for other developers who are also in the ecosystem.
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.
Entirely 100% true. I can count on one hand the times I've said "wow, this documentation was written by someone who cared". Threejs is a good example here, but even then it is subject to API rot and needless reference chasing.
Examples are often the best way to do documentation, sadly.
I've been leaning on test suites more and more for this. It's almost like a test suite should contain comprehensive tutorials. You know the API is good (hopefully) because if it isn't, the CI/CD pipeline wouldn't have let the release through.
I guess I disagree that it's a good thing.
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.
> Beginners have to be nurtured through lots of context that builds up slowly.
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.
I find that a lot of project homepages (or GitHub README.md these days) are riding high on "if you're reading this, you already know what this is for" energy.
What I would give for people to approach documentation in a more empathetic way; tell me what something is for, what problem it solves vs other competing solutions such as X or Y, whether it's still the best solution or in maintenance mode because another tool has become dominant.
Give me the tools to construct my own pros and cons matrix, without assuming that I'm an expert. Put five minutes into asking yourself "what questions are people likely to have, even if they aren't sure exactly what to ask" and write that down.
I'll never understand how someone can spend months or years of free time building something, but then actively sabotage it by not making it easy for people to realize that they've found what they are looking for.
It's also really valuable to keep perspective on the different kinds of documentation. https://diataxis.fr/ is a really solid starting point for anyone aspiring to create better docs.
This issue with READMEs in particular has driven me nuts for the decade I've been doing ROS related robotics stuff. So many repos where the only surface clue (i.e. before diving into the code) of what it does is your interpretation of its name.
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.)
Lately I’ve been asking Cursor “what does the program do?” Was actually pretty helpful as a starting point.
Oh yeah, definitely. Great for my own "throwaway" or rushed projects that I want to revisit, too :D
I echo this sentiment. Whilst I completely understand that developers are doing this in their own time and largely for no other reason than it being a labour of love, it would really help lower the barrier to entry.
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.
What I really really want to read in a README is *why* did you build this? The "rationale" section of a README is almost always the most interesting part.
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.
There was a project posted here once that didn't even bother saying what the thing even was!
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 was the most fun I'd ever had in a game, but it was also instructive. The battles were famously difficult and required a ton of coordination and strategy, and even a small mistake could get everyone killed. So our policy was that everyone in the raid had to sign onto our Teamspeak server, which was basically an audio-only Zoom call where my appointed officers and I could give orders and dictate strategy.
I very quickly learned an important lesson in communication: assume the worst. Surprisingly (to me at the time), most people who don't understand what you're saying won't stop you to tell you they didn't understand. And so I came to live by two rules:
1. If it's worth saying once, it's worth repeating. Assume people are only half listening, that they're distracted, that they're not paying attention.
2. Don't assume people know what you know. In fact, while talking, keep a second thread running where you explicitly ask yourself, "What am I saying that my listener might not know?" Then explain it.
The more I followed these rules, the better we did on our raids.
But even long after I stopped playing WoW, both of these rules have been helpful. Especially the second one, which helps overcome the curse of knowledge -- the phenomenon that occurs when a person who has specialized knowledge incorrectly assumes that others share in that knowledge.
Thinking about the curse of knowledge when communicating basically becomes second nature after a while. And then it becomes obvious when you observe other communicators who don't care about the curse of knowledge. They confidently launch into stories using obscure terminology and acronyms that nobody understands, without a care in the world for their listeners' understanding, they don't notice at all that nobody understands.
I remember being in a raid guild. The guild leader was this random 18 year old kid. I remember noting that this kid was expertly herding cats, many of whom were much older professionals, with absolutely zero direct authority, across multiple timezones, and getting them to not only agreeably distribute valuable loot, but also coordinate them through intricate boss dances and more intricate event scheduling. I thought it was a real shame that this wasn't direct evidence that he should be hired into a people management role immediately.
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.
One of the things I've tried to teach people I've mentored over the past few decades is the principle of "Sharing is better than assuming." If you know something, share it with other people. Don't assume that they know something. If they do know, and you tell them, then you've only really confirmed what they already knew. If they don't know whatever it is you've helped them immensely and made whatever it is much more accessible.
Occasionally people will complain that you're being verbose and adding detail that they didn't need but in those cases you can usually just say "oh, that's just in case a [junior|manager|customer] sees it." People don't mind if you flatter them that the explanation was for other people.
It applies as much to development as it does to investment reporting, people management, delivery management, etc,
I have encountered a number of people who exhibit startling hostility at being told something they were already aware of. While I cannot currently recall a specific example, I strongly suspect I have previously felt this way myself.
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.
When someone makes a search and lands on your tutorial, you are not giving him unsolicited information.
You would be if it's a tutorial on audio codecs and your tutorial starts with connecting the power cable to the computer, clicking 'log in', and don't forget to breathe!
> One of the things I've tried to teach people I've mentored over the past few decades is the principle of "Sharing is better than assuming." If you know something, share it with other people.
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.
> If they do know, and you tell them, then you've only really confirmed what they already knew.
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.
Would asking them if they already know or would like something explained be the best thing to do (rather than assuming one way or the other)?
That can also easily be misconstrued.
Most tutorials aren’t for non-developers. They’re not for developers, either. They’re a bunch of prose I want to skip, and then I finally get to the steps I’m really looking for, but the author left one out, or assumed some weird development environment or IDE I’m not using, and I have to give up and go back to Google again.
The problem is that writing is hard, because it’s for people outside of your head, while you’re inside of it. As toddlers we learn that our senses aren’t immediately accessible to other people, but many of us never master the art of remembering that knowledge and experience inside our heads isn’t available to you, the reader, until we write it down.
Oh, and maybe if folks thought “cookbook” instead of “tutorial” when they’re writing, the result might be organized better for the rest of us to use, and less likely to become useless after the next point release.
Ironically, online recipes of the cookbook kind are actually much worse for meandering and irrelevant prose than programmer blogs are.
When writing documentation, you need to establish a baseline of required knowledge and skills for your audience. You can choose any level, but deviating too far above or below that baseline will inevitably frustrate some readers.
When this happens, you can either make excuses or focus on solutions. Problems can be difficult, but with modern tools like AI systems, Google, or even books, it has never been easier to overcome them. If you don’t know what a Shoobababoo is or why you should use the quagmire instead of the hoobastank, you can look it up. Ideally, documentation would contain every answer with minimal need for external knowledge transfer, but the world doesn’t owe you that convenience.
> you need to establish a baseline of required knowledge and skills for your audience
So many guides for setting up like... "control system simulation" or "industrial automation compliance test-bench" start with "double click the exe and press next".
Baseline for expected knowledge for the user of the guide is SOOOO important.
"What is an exe?"
I write stuff for our internal teams and it's usually for sensitive systems where you can cause a lot of problems if you make a mistake. I will often start the doc by saying "This assumes you know how to use x, y, and z. If not, then you probably shouldn't be doing this." We limit access already, but some of these could be used in a DR scenario by someone who is not super-familiar with the product. I purposefully will not explain certain things because if you can't figure those out, then you shouldn't be doing these steps.
This is primarily the reason why I stopped writing books and started making tutorial websites. There are so many interactive tools like <abbr> 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 yet most content is just these lazy walls of text. Event OP here uses footnotes that just scroll to the bottom of the page adding very expensive context switch for the reader rather than take advantage of the web browser capabilities like hover or modal pop ups.
Hello, I am just now trying to upgrade my blog. Can you please point me to sites that do this right?
An extreme example would be gwern.net -- specifically you might want to read https://gwern.net/about and https://gwern.net/design
Thank you. That is indeed quite extreme - I could use an article progress bar, footnote pop-ups (maybe, link back into article might be enough). Definitely not doing my own window manager. I'll try and read the rest of the design page with fresh eyes, maybe I'll learn something else.
I guess many tutorials are not made for absolute beginners and they have assumed you have learnt the basics before jumping into their topic. For example, if you never learn programming and set up an ide before, it has no way you can learn OpenGL as your first tutorial, and all the syntax and commands will look alienated.
And you can't write every document with an assumption that the reader knows nothing. Each document would end up the size of a phone book if you explained every single piece of technology used and provided tutorials for them.
Knowing where to jump in your stack is a tricky question, though.
OpenGL is not so bad because the API is quite stable. WebGL in particular is great because there's literally zero setup you need to do for executing it.
Integrating with Linux/Windows display surfaces is disgusting however. KMSDRM is way, way better than the nightmare that is X11 and Wayland.
My recent experience with getting an app deployed from Gitlab to a kubernetes cluster on DigitalOcean was exactly like this. There were like 3 or 4 different third-party technologies I was expected to set up with absolutely no explanation of what problem they're solving, and there was a bunch of steps where I had to supply names or paths as command-line arguments with no guidance on what these values should contain (is it arbitrary? Does it need to match something else?)
Mind you, I have relatively good Docker experience (wrote Dockerfiles, have a pretty extensive Docker-Compose - based home server with ~15 services) so I'm not new to containers at all. But man, the documentation for all these tools was worse than useless.
Personally, my main problem when learning new things is that, once an ecosystem has matured to a certain point, there's a baseline of knowledge that everyone inside that ecosystem has. In anything I read about it, this knowledge is assumed, and if I search for it, all the old articles that talk about it are either no longer available or just wrong, because that baseline knowledge gradually evolved as the tech matured, unnoticeably to the people inside the ecosystem.
This is an area where I find LLMs to be extremely valuable, as they often still contain that knowledge and can explain it to me in a way that makes sense.
I tend to write overly-long tutorials [0]. They are usually aimed at developers that reflect my own capabilities, but about a decade ago (in experience, but not tech). I write about relatively specific, advanced topics, aimed at folks with a baseline level of understanding.
I use a lot of well-tested code samples.
Writing for true newcomers, is very difficult, as there’s a lot of context-building.
My code documentation[1], on the other hand, is written for folks at my level (I basically write documentation that I want to read).
[0] https://littlegreenviper.com/miscellany
[1] https://littlegreenviper.com/leaving-a-legacy/
Clearly the author is not the target audience and is trying to read a text they lack the foundation for understanding.
This is very different from bad documentation or writing.
Not everything should be reduced to eli5.
So many tutorials will just assume everybody's system, workflow, tooling, etc. are exactly the same as theirs. How many tutorials start with just "brew install"? It wouldn't take much time at all to say "You can use Homebrew to install this - here is a link to install Homebrew for macOS and Linux"
My personal favourite is when I'm trying to debug something and the suggestions all say "sudo xyz".
Thanks but if I could have used admin permissions to dig deeper I would have done so already. A lot of us can't do that on company computers.
I don't see why there's an expectation that a "non-developer" should be able to understand documentation or tutorials written for beginners. It's a specialized field with technical jargon. There's a reasonable expectation that the person reading your tutorial is at least marginally competent. Beginner doesn't necessarily mean "non-developer." It could as well mean "new to this stack/technique/idea." I know this was written in good fun, but the implications that you shouldn't need some baseline competence to work through a tutorial is just wrong-headed. It benefits the reader to run into roadblocks and work through them. That's how you learn.
I call it "Kindergarten speak". People at the highest level of technical expertise sometimes have it, where they can patiently, and in understandable terms, explain to the most junior (but interested) party so the stuff sticks.
Others, while extremely nice and helpful, just don't "get" that their advanced jargon or, in my workplace, advanced mathematical language/notation, however elegant for themselves, is a huge hindrance for those not as versed in the art.
So if I, personally, say someone can explain something in kindergarten speak, that's the highest compliment. The more advanced lingo/notation stuff can come later, once the explainee has the big picture.
This is obvious for us who believe in and spend time on writing good documentation, but there are a surprising amount of devs out there who don't. "The code speaks for itself" people. Never understood them (literally) it's like some cult from the middle ages.
> How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner
Such Jargon! What's a developer? some kind of person who takes my fujifilm and gives me photos? And why do I care if someone is not such a person. Tutorial? what is this stuff do I need to sit in a small classroom? How do I read some college students sitting bored in a classroom?
This reminds me of the Rockwell Retro Encabulator[1]. I understand the frustration.
[1] https://www.youtube.com/watch?v=RXJKdh1KZ0w
I was thinking about the same thing. Such a classic!
This 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.
I've been coding in C++ since the 90s, that's also how I feel whenever I'm required to build something using cmake.
Which is funny, because it's probably the easiest to use (common) build system around.
I beg to differ. It's only easy for projects you're constantly using daily. People tend to build all sorts of abominations with it.
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 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!
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.
I had to install vcpkg yesterday for the first time. Well, actually, I ran into a problem last week that could have been solved by installing vcpkg. I also happened to read a comment here on hacker news recently that mentioned vcpkg (but I didn't know what it was).
The problem was that 'cargo install cargo-show' wanted access to an OpenSSL installation (under Windows). The long error spew did mention vcpkg once or twice so I googled it and got very confused by the readme.
So I tried to install OpenSSL without vcpkg. That worked ('winget install openssl') but 'cargo install cargo-show' still didn't. Perhaps I had set up some environment variables wrong.
Yesterday, I finally figured out how to install vcpkg and it was indeed very simple, despite its readme. 'cargo install cargo-show' still didn't work -- it couldn't find openssl installed with the right "triplet" even though it was clearly installed in a way that should work for all 64-bit x86 Windows.
Setting OPENSSL_DIR and then running 'cargo install cargo-show' worked perfectly.
Apparently, there are different ways the directory structure for a vcpkg installed package can look and the vcpkg/openssl gave me one and the build script for one of the dependencies of cargo-show expected another.
Very, very confusing.
I think you can get away with just using 'winget install cmake' and then invoking cmake with the right command line to make it play nice with vcpkg (and that command line is listed in several places). I haven't tried it, though.
'vcpkg integrate install' sets up some sort of secret integration with Visual Studio -- maybe vcpkg learns where VS libraries and binaries (compilers/linkers) are hidden and maybe Visual Studio learns how to invoke vcpkg.
If you run it, it will also tell you to how to integrate more explicitly with cmake:
I hope this makes it slightly less confusing.The main advantage of cmake is it's slightly easier to use than autoconf so long as you stick to the path. Do not attempt to leave the path. Also the path is poorly signposted.
That is the typical experience for C++ tooling lol
C++ is written by 99% professional architecture astronauts who do fuck all in terms of valuable software. I will die on this hill.
C++ might have been developed by architecture astronauts, but it's used to build a ton of valuable software - KDE, Windows, Spotify, etc etc...
HPC?
Windows NT?
GCC?
Video games?
I'm a veteran C programmer with a deep dislike of C++, but to say it's not used for valuable software is just wrong.
The language committee only makes it harder and more astronauty every year. How many Unreal Engine developers from 2007-2013 understand CPP20/23?
I agree with you. I'm no fan of C++.
With that being said, it is (and has been) used to produce valuable software.
You never need to use everything a language provides. You find the parts useful to you or your team and use all of them.
I was a C++ developer for a decade and knew a fair amount of the C++13 spec but never needed to use even half of it in production. I've been a Java developer for years and don't know 10% of the standard library there. That doesn't make either language poorly designed by itself.
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
Linux is a pretty valuable example of such astronautics. Also things like TCP...
I hope you don't die on a hill tho, not anytime soon at least.
Hilariously incorrect take. Zero CPP in the Linux kernel. Torvalds openly hates CPP.
EDIT: thank you for your well wishes though :)
Huh TIL, my apologies.
When I started with programming I didn't have issues like this at all. Most problems that I've faced where of the kind that when you compile or build that it didn't work and you have to spend hours going down the rabbit hole of dependency hell.
This article begs a more important question, is the burden of understanding the article / tutorial on the reader or is the burden of making it understandable on the writter?
I think a reasonable amount of knowledge about the topic being discussed in the tutorial should be expected from the reader but this should also be communicated by the writer.
Most docs I read have their prerequisites spelled out.
This is the version of this OS with this plugin that this guide is written for.
So when I find that, inevitably, something has moved, I can figure out how my setup differs and search for the difference.
If you cant stand up the prerequisites, then the doco isnt for you, you should be searching for documentation on how to stand up the prerequisites.
Funnily that's one of the first questions on my mind when I look at a new program or library. What was it written in or what platform for, what's the build system or requirements and what does it actually do. Quite often I decide to avoid a thing entirely when I can't figure this out after reading the main documents. Sometimes you can look at the repo tree and just know, but often not.
This should be the first sentence in the landing page or README IMO. Instead you get something that looks like marketing copy written by LLM fed on BS generator output. Many projects just seem to refuse to tell the prerequisites at all.
When I was at the head of the jailbroken iPhone ecosystem, I put together a tutorial for how to get an SSH daemon set up on their phones. I put a lot of effort into making it something that anyone could follow, step by step, and achieve the result, making sure to skip no steps, assume no knowledge, and with screenshots showing the interface.
I soon thereafter received an e-mail from someone saying that they had excitedly followed my tutorial and found it very easy to follow; but, they had now gotten to the end of the instructions, were staring at some text that said "mobile@iPhone ~$ " (or whatever the default bash prompt was; I do not remember) and they did not know how to proceed.
I had similar experiences over the years, and I had a realization at some point: if you provide someone detailed step-by-step instructions for how to find the dragon, part of the UI/UX of the tutorial should be that you don't actually feel comfortable following it if you should not be doing so: the difficulty of the path must scale with the goal.
This is similar to real-world affordances, FWIW: if a user should not be opening a panel unless they are ready to do maintenance, yes, don't go out of your way to make it hard to service without permanently damaging it (that's evil), but, maybe, screwing the panel shut is more appropriate than providing a pull tab, due to what the latter implies.
A lot of users find this annoying, because they think they want to do X, and they just need better step-by-step instructions... but, that's just not how the world works: a lot of times, what you need to do to do the task is, in fact, a basic knowledge of the entire system, sufficient that you will need a fraction of the instructions (if any).
On the other side it causes another problem, BTW: if you make instructions that anyone can follow--including people who probably aren't at the level where they should do so yet--you also end up with instructions that are more difficult to follow for the people who should be doing so, as they are extremely verbose and often narrow in their scope.
It also sets up perverse incentives to try to make the instructions even easier to follow, well past the level of easiness the task should actually be at, which, again, causes problems for the people you actually want following the tutorial: if you find yourself creating little docker containers to avoid saying "install a compiler"... no.
FWIW, I was one of your users - back when it seemed important to jailbreak my iPhone - and I appreciate the work you put into it. I'm guessing that it was pretty thankless, for the most part.
Brilliant to see something from you here - a long time ago, I was there as well using your products and making a mess of things with stuff like afc2add and iPhoneBrowser
I wonder if there's just a mismatch in what 'a beginner' means. Perhaps the tutorial is aimed at beginners _in this specific topic_ ? I have also read 'intro to x' tutorials and had to do a lot of wider reading, I just accept that's the cost of trying something outside my area of knowledge.
I am surprised nobody mentioned the curse of knowledge: https://en.wikipedia.org/wiki/Curse_of_knowledge
It is actually a fairly well known phenomenon, certainly in educational circles. Being aware of it when you are writing any form of documentation is a first step. But even then, it is very difficult to properly assess the knowledge entry level of your audience.
Having others read through your documentation and importantly work with your documentation is a good strategy.
One thing I can also highly recommend is simply start out with a list of assumed prerequisite knowledge in your intro. Specifically things like certain environments, frameworks, etc. Bonus points for not only listing those but also linking to the documentation for those.
Tutorial is effectively a list of written orders. Problem is that if orders are not written in a detailed and specific way, person on the other side can interpret it in wildly different way.
This has been, and still is, a huge issue for military. Whole battles has been lost because order from a general was too vague or too open to interpretation (General Lee has been infamous for issuing vague orders which screw him up on Gettysburg). Prussians has invented whole wargaming which effectively has been generals writing orders in one room and officers pushing model armies in another room and reporting back to general in writing.
LLM is very good at filtering who can ask a correct question - order LLM what to do. People who can express themselves and describe problem will always get more mileage from LLM than people who will just throw vague request on it.
What it should look like:
Have a bunch of checkboxes at the top, one for each buzzword, each technology and all other things a 12 year old wouldn't be familiar with.
You check which you think to be familiar with and all other things unfold a short description with links to similar interactive documents.
Each section comes with 1-5 star rating for how well the reader understood your explanation.
Then you gather the data as the subjects suffer though the tutorial.
If people come from specific backgrounds further tailor the explanation for them.(Like babazoofoo for C++ developers.)
Let there be a browser extension or an API that checks (and hides) the familiar boxes for you.
I didn't say it was possible to make. It would be glorious to have. If you know all the tech involved the whole thing implodes into a one line code example.
This is a nice idea, but looking back at how not only documentation, but also UX in general has not improved the slightest over the last decades, it's fair to say the only way we'll ever get close to anything like this is by leveraging personal LLM assistants, unfortunately.
Back when I was teaching myself Spring circa 2015 there was this one guy called mkyong who literally just did Spring tutorials - his site's still online at mkyong.com[0] - and while I did occasionally use Baeldung and the Spring docs, it was ultimately mkyong's tutorials that got me where I needed to be. The Internet is full of these kind of unsung heroes who happen to be really good at spelling out how to do something so simply an idiot could follow it. You kind of take them for granted as you train yourself up!
[0] https://mkyong.com/tutorials/spring-tutorials/
But is this tutorial meant for a non developer to read? I would imagine a linguistic psychology tutorial would have the same effect on a dev written by an expert.
Yeah, this poor guy stumbling around the internet who should be reading kids books keeps clicking on kubernetes how-tos
Code samples. This is what’s missing most of the time. Even if you encounter esoteric jargon, if they give a few examples, it’s pretty easy to decipher. Even big companies like Google give code examples in multiple languages.
Indeed, if the author had added this code sample, it all would have been clear.
---Said in light-hearted jest, and not in sarcasm
You are a beginner for a short time. Once you get your bearings you will beg for more resources beyond a beginner tutorial.
A serious framework, language or any other tool geared towards production, has to be supported by docs, tutorials and (where possible) a community of people actually deploying this stuff, possibly at scale.
I wonder if we'll see another post next year when OP realizes there's virtually no content for the Shoobahooba Snarfus ecosystem beyond some 'get started' guides.
> You are a beginner for a short time.
If you have the right mindset and consciously seek to progress past it, yes.
I can recall seeing people spend years on concepts in a way where I really couldn't rule out the possibility of dedicated trolling. I remember one who would repeatedly ask about fixing problems with code examples using various advanced (at the time) graphics APIs while clearly missing several fundamentals about writing code in the language. And who also seemingly refused, the entire time, to adopt the proper spelling of "variable", despite it being corrected by multiple people in every discussion.
This is spot on, and can apply to anyone branching out into a new area. I will add this concrete piece of advice that can simplify things:
Don't ask the user to install tools or use ones that are not core to the topic. I still have a bad taste in my mouth from the 2 Scoops of Django tutorial after getting stuck installing VirtualBox, Chef, and Vagrant. The solution was to just not use them, because they don't have anything to do with Python, Django, or making a web server.
I could say the same thing about me "non-legal person" trying to read any contract, terms of service or a license document. Many people tend to make fun of the developers speaking a different language, without realizing, that they do the same in their respective field. I think clear communication is important, but you can't expect anybody to write tutorials aimed for every audience. Learning is hard and it takes time to navigate through all the buzzwords and terms, but that's what learning something new requires.
I don't get it. I learnt to program from tutorials in the early 2000s. I guess at some point in my education I also learnt how to look stuff up. It turns out that was the real skill all along, I guess. So the question is why do people find looking stuff up so difficult? Can you imagine how long every tutorial would be if it started from the bottom? "If you want to make an apple, you must first invent the universe."
We devs are really good at answering two out of three questions:
1. How? This is the tutorial. It might be really helpful, for specifically what is being taught.
2. What? This is the reference documentation. It's often the most usable and complete resource.
3. Why? This is the context. It can only be learned by getting familiar with the environment. This journey is where we devs grow our metaphorical (and sometimes literal) neckbeards.
---
We could stand to pay a lot more attention to question #3. The contexts we have surrounded ourselves with are messy, conflicted, incompatible, and surprising. Some particularly savvy devs have made incredibly powerful tools to help clean up this mess, yet somehow those tools are some of the least noob-friendly software we have! How did we get here? Is there any way out?
I think the most uninviting part of our environment is also the most familiar: the shell. There are a lot of pokey bits that we really don't need anymore: escape sequences, suspend, environment variables, etc. What would happen if we took a serious look at starting from scratch? Could we do better than a REPL?
It's pretty incredible that after all these years, no one has actually made a real competitive alternative to the shell, and I have a theory for how we got here. The GUI model was created by corporations for proprietary software. We call them "applications", because they are supposed to cater to a specific predetermined use case, which is precisely what makes them inferior to shell utilities. This development model isn't limited to GUI either: apps have taken over the entire development scene.
I think if we really started fresh, we could revolutionize modern software to be more compatible, flexible, and malleable than any application could ever be. That's what a shell is already, which is why we devs never want to leave it behind.
Right now I am a tech writer and the curse of knowledge is hard to break for many people. I've gotten a lot of docs from devs that are obviously just reminders for themselves of what they already know. I've had to flesh out docs that just stop halfway through a procedure.
Please just admit that writing docs is hard. Because it is. Just because there is a lot of writing going on in college doesn't mean you learn how to do technical writing, academic writing is very different.
Go to the support team and ask them what questions are they sick to death of having to deal with (hint: its usually something you would think is pretty easy) and rewrite the doc to handle it. Then watch what happens to the support questions, if that disappears you did it right.
This has been a very informative and entertaining evening for me. I loved reading the comments. Also thanks for all the guestbook posts, they bring me great joy. May your Snarfus boop correctly forevermore. Devs are great.
—Annie, not a dev
The hidden files >_<. The classic "edit config.yml" step with no idea where the file should be. Special bonus for RKE2 would used to not even mention you had to create a folder to put the config file in because their install script does not do it for you.
But a part which is not mentioned in this blurb is locality of information. A good example would be traefik documentation where every part of the doc is written like you've already read all of it. Usually with not even a link between the different parts mentioning each other so don't expect something like a table of values where an option is mentioned.
"But you should learn all of it if you want to use it". Sorry but nope. Most people using your documentation will be of 2 types:
- they want to check what your software can do and will just try to get something running fast. So you need a good "get started" and some "how-tos" showing what it can do - something is burning in production, they need a solution fast and it seems the problem is your piece of software which they don't know. You may want a guide on how to debug your thing. At least you want relevant information to be fast to get and easily googable.
I have not laughed this hard in front of my computer in a long time. What a gem. (as a non-developer also, this experience really hit home)
The title here is beginner developer, but the article states non-developer.
Nevertheless, dev docs are usually written for reasonably experienced developers, but new to specific framework/library.
These docs would be too long-winded if they were to account for non-devs/complete beginners.
Please, don't cater to that audience in your docs.
These days I dump code into an LLM, ELI5. Then ask it to tell me logical chunks and overall structure. I then go from there.
As 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.
But you are starting at a level that assumes you are no longer a math beginner but rather a beginner in this particular area. If you were reading a high school algebra textbook, you shouldn’t have the same issue.
It's people sharing with others of equivalent skill. Use an LLM to adjust to your skill level. The times I write this it's to document something that worked. There's no guarantee it's what will work for you. You're supposed to translate it. So it's not really written for you.
On the flip side, it's taken me a long time to break my skimming habits and read slowly when I'm a novice in a new area. Especially with math or software engineering, it's often necessary to stop at each word I don't understand, unpack it, and gradually build a scaffolding for myself. This is very slow, but it pays dividends extremely quickly.
As a rule of thumb, it seems like skimming is useful if one already have a good familiarity with a subject and the content is slotting into an existing mental framework. However, when that's not the case, skimming gives me the feeling that I've learned something without much real progress.
I 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 hoobastank without a major gLibc upgrade. I got shamrock talking after compiling the compatibility shim for single-threaded pintafore and migrating from Debian to Fedora 75bit, but then the fistifunk socket closed! A few more hours troubleshooting and eventually figured out the root cause: The Snarfus node's DNS resolver was down. Turned it back on and everything worked perfectly.
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.
Not emulator, emulater. This technical term may also hyphenated, emu-later.
Emu-laterrrrrr… and Doug.
I would bemoan the effectiveness of the advertising on me, but it’s just nice to see somewhat traditional advertisement styles working in the age of 5 second ads.
Wait really?? I also wound up migrating to Fedora 75bit for basically the same reason (TopHat doesn't even support hoobastank). But then I couldn't find `file` in the specified directory. I have
`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.
It was moved to a new path so you have to create symlinks in both locations to the new path under /usr/lib/newlib1.2/newfile.so otherwise, You can download a script that will make that for you but it will only work if you have all the dependencies for that script installed and their version numbers match the ones that the script owner had when he wrote the script.
This answer is correct but it only works under a new moon if you implement while smoking a joint rolled in pink paper, which should be doable.
So sorry about that. I should have mentioned the DNS resolver as a potential issue because it’s always DNS. Terrible oversight on my part, probably because I am not a developer.
Oh please, this is why it's _clearly_ superior to run Catenary or P. Papua
One of my first policies: Every time we have a new hire, the first thing we do is have them go through our onboarding documentation and ask them to make corrections, improvements, and add clarifying notes.
It's their first contribution to our code base.
It's not just programming tutorials, but it's a phenomenon that is widespread [1].
[1] https://en.wikipedia.org/wiki/Curse_of_knowledge
Sounds like you may not be ready to read this tutorial just yet. Maybe get more experience in the terminal, and read docs on specific languages (elixir has good ones, for instance) or take a hands-on course (like Codecademy Javascript, etc).
Then, once you have more experience, you can go back to that tutorial and try reading it with more polished eyes.
What you've posted is the equivalent of me taking a new interest in cooking but applying to culinary school. If I haven't cooked in a real (production, high volume) kitchen, it's all gonna be Greek, overwhelming, and turn me off.
Unfortunately, the curse continues: follow up with how the text gradually coalesces as understanding grows. Realize how much easier it is after completion. Forget what "don't know what one doesn't know" felt like.
At least the beginner perspective captured enthusiasm, empathy (an alternative error condition for a path to a hidden file), and the request for feedback.
I wrote about this a while back [1] because most documentation is just plain bad. At best it's a reiteration of what is obvious and at worst it doesn't exist. Far too often it says too little of the bigger picture and too much of oddly specific edge case details. If I can't come to your project from 0 knowledge about your project and get it running without tearing my hair out, the docs failed.
[1] https://mc-deltat.github.io/articles/what-the-f-is-this-code...
That was a good bit of humor.
Also there are some popular ways of explaining things that don't do the job (your experience is maybe different). For example: try to learn very basics of object oriented programming. The tutorial will inevitably have examples like "Class Bicycle" or "Class Car". These are out of programming context and never helped me to understand how to benefit from OOP in programming.
Another example is git tutorials. Having used git for years it feels so simple. In the very beginning it wasn't and those maps with circles and arrows didn't help.
Class Car isn't a bad place to start. It's a real example and something you will find in professional game engines:
https://dev.epicgames.com/documentation/en-us/unreal-engine/...
A lot of kids who learn programming are motivated by a desire to make video games, and everyone already knows what a car is, so such class hierarchies are a good way to teach the concept.
On HN it's trendy to bash OOP and inheritance but it's a bubble; contempt born of familiarity. Real world codebases all use it extensively, including new codebases, and they use it because it's often a reasonable point in the design space for modeling problems. It's not perfect but the alternatives all have major issues of their own.
Obviously once a budding developer realizes that he can't find a job writing game engines and 'graduates' to writing DB driven web apps, the objects and class hierarchies he finds will be representing much more abstract concepts. But by then he'll understand what those concepts are, having mastered them in a less abstract concept space.
We did something similar with 'prod' code reviews. We started including a couple of the more junior folks in a pre-release review that was mandated. Intent was to say fine, id tech debt, or pull the andon cord if something was missed that would impact prod. What came out of it were their questions - which almost always was translated into an ask for documentation for that bit of code. The secondary bonus was they learned the questions that would be asked of the people who were merging.
"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...
This hits home, and not even relegated to software. My partner decided to learn to ride a motorcycle during the pandemic. I’ve been riding in some form or another for more than half my life. In the first minutes of attempting to explain the procedures, I immediately realized there were years of involuntary movements and coordination I failed to articulate because it wasn’t a part of my mental model of the process.
Needless to say she signed up for a professional course, got the license, and we’ve travelled nearly 10,000 miles together since!
Why be so snarky? Documentation is there for users, it should assume that the user has the necessary background. If the user doesn't it is his responsibility to read up on the relevant background.
Pushing the burden of education on every single developer writing a tutorial is absurd. It makes the documentation unreadable to the people who need it the most and wastes time and effort. This style of documentation is totally fine.
Education is your own responsibility, do not push it on others.
Yeah...
I usually go over my guides and tutorials and try to remove jargon when possible.
However, I also try to clearify the target audience.
When I write a tutorial about storing files on S3 with the AWS SDK for Node.js, I won't start by explaining what JavaScript is.
Still, if I write something that has a reasonable chance that it is read by many programming beginners, I tend to add a link to FreeCodeCamp courses that help the readers to get the minimal education to follow my piece.
This is very funny, but developers usually aren't writing development tutorials for "non-developers."
Even the submitter must have realized this, which is why they changed the title.
How I, a professional developer of 15 years, read the prose-heavy README you, a developer, wrote on your repo.
All docs should start with examples. Some docs would be better if they ended right there.
I’m not doing this either but: ideally tutorials should work on a very well defined environment (clean install, VPS with X setting, application deploy at version X with plugins at versions A, B, C)
Then they should have a unit test. And a passing status. The problem with most tutorials is that they simply rot. So many times they tell you to do a command with a flag that doesn’t exist, install two incompatible packages or click a button that isn’t there.
This level of extreme hyperbole is silly and not in any way helpful. Try analyzing an actual tutorial (which will only be an analysis of that one--quality varies a lot).
That was the analysis of an actual tutorial.
Oh? Which one?
In other words: No it wasn't, and you know it wasn't. There's word for that.
Good observation. Silly is the point. You nailed it.
So your point is to be silly (what you call "good clean fun"), not to offer a valid criticism or to be in any way helpful--yes, I nailed it.
> I really appreciate the folks who take time to share their knowledge and write up tutorials and give tips and so on.
One wouldn't know it. Many here are foolishly taking this as a valid criticism of those folks.
I'm a developer and I read most tutorials like this.
Pretty much every "thing" I come across today uses some kind of dependency that I have little, or no, experience with. Unfortunately, even though the "thing" might be interesting, the fact that I'll have to spend 4-16 hours futzing with things that are completely new to me to get somewhere is often what turns me away.
This article doesn't hit any nail on it's head. Tutorials and instructions of software are of the best quality they have ever been.
The real title was, How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner
The edited title does not have the same meaning. Why was the done? How often is this being done? What else is being changed?
If I write a title on my blog saying, I like Java, what is to prevent you from changing it to I hate puppies.
One minor tip that I think can have a big impact: whenever writing down something to run on the command line (e.g. for documentation or other kind of sharing), always use the --full-version of the flags (instead of the short -f version). The extra information it conveys is worth a lot. If someone gets tired of typing it, it's easy to find the short version.
> Just for shits and giggles, you can de-sham the chronostatiomatrix by running —()()(]]asdg a=-do —cd go cd stay —sususudododo baby shark—][] but that’s optional.
Except in most real cases you're following the tutorial for, where it is both mandatory and non-obvious it's not been done.
Something like the mock one here I think is really more often largely intended as a sort of logbook entry, a note to self, 'how I did x' (in case it breaks, I need to do it again, update it), it isn't really 'for me', the other.
It's always a problem that you forget what you use to not know.
When I first started writing some internal docs/tutorials at work, I was new to Linux. So I generally took the time to include tangents into explaining fairly basic Linux concepts, because they were new to me. They were rough edges I had to get past so I wanted to help others do the same.
Five years and a shit load of Linux experience later, I don't do that anymore. That stuff has become so second nature to me that it just doesn't even occur to me anymore. And I just don't have the damn time. If I had to stop to explain what cat or sudo or | mean in every doc I write I wouldn't have time to get anything done.
You could replace specialized terms with nonsense words in anything. This is completely non-actionable critique.
In the end, there is no Royal Road to learning. You have to create put in the effort to create new concepts in your head to understand something.
If you can't understand half the words, you're not the target audience, period.
> 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
good job, you missed the point
Great job, you've failed to document the point.
Regardless of the level a tutorial is given at, there is information that is missing. A well written tutorial knows its audience and contains all the information for that audience.
Sure, I will grant that someone who doesn't know what a computer is shouldn't be expected to follow a tutorial to install PostgreSQL on a headless linux server with proper security protocols in place.
The issue is more that it's extremely easy to assume someone understands what "primitive file operations" are necessary to accomplish a goal, and fail to describe what it is the user actually has to do.
Just because you understand how to navigate a file structure doesn't necessarily mean you have the domain knowledge necessary to make leaps that are frequently present in tutorials.
> there is information that is missing.
What information was missing?
> and fail to describe what it is the user actually has to do.
How is "go to a folder and copy file content" is not such a description?
> doesn't necessarily mean you have the domain knowledge necessary to make leaps that are frequently present in tutorials.
Again, rather than speaking generically, how does this post demonstrate it? What leap is present in "this tutorial" that an average reader would not have the knowledge to make?
You’ve assume your beginner knows that In the Terminal meand open the Terminal application, knows how to open the Terminal, knows that the Terminal uses typed commands, knows that typed commands are followed by Enter, and knows that the text following Terminal are the typed commands to be entered.
The non-garbling threw me off (it wasn't jabbernocks), so assumed some passing familiarity. But even granting that, you can add a few minutes and a few google searches to your complexity budget.
If anyone has an open source project and wants a review of their README and docs, please get in touch. I enjoy providing this type of feedback, and I think every project can benefit from it.
I once was asked to teach a class in beginning C++ that was put in the paper as beginning programming in C++. Some of the students really weren’t ready for the class they found themselves in.
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.
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.
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.
I prefer to think that updating the documentation isn’t fixing the root issue, and that the working systems are their own documentation if explained properly, so document in such a way that they can’t become outdated, when feasible.
But is it a tutorial, if it's as described? Or someone's hasty notes?
Is that format better or worse than the SEO tutorials that spend half the time explaining what a conditional statement or a loop is?
Makes me want to revisit my (started, but not posted) screenshots and videos of trying to install matrix / element following the random directions / docs.
The funniest part, lol
On Fedora you'll find it in: library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam.file.d/boop_settings.cfg
I went to library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope but I don't seem to have a /never/ folder at all.
That is true, especially when instructions are spooky like
And people run that without thinking.Honorable mention: https://youtu.be/aW2LvQUcwqc?si=IqPtgd3cxpUKwWRm
i started frequenting hackernews because i knew that tutorials written by developers would start making sense if i just kept trying to read them. it worked!! took a few years though.
every publication has a target audience.
A paper in a cancer journal and a Web MD blog can discuss the same disease, and both will seem like a foreign language to the wrong audience.
And now we have LLMs, most of the "trade words" and jargon can easily be translated into a kindergarten reading level if that's the reader's background.
OPs argument is flawed. Documentation is not there to teach you from scratch. Its there to describe a projects intended behaviour under normal conditions. Often times people will cry about lacking context and expect you to basically use it for them. I would heavily recommend against that as you will end up as unpayed and burned out tech support...
OPs everything is flawed but she tries really hard.
If this is you trying really hard ...
nice alt
This mirrors my experiences 20 years go, but I actually appreciated it because it pushed me harder to learn the dev arcane languages.
Thanks for this. I never knew how much I'd like it if George Saunders started a tech blog.
Omg this is high praise I’ll never be able to write anything again
Next time I won't forget to improve my life by running sususudododo baby shark on a regular basis.
Honestly, I'd say this doesn't even just apply to beginners to software development. It's applicable to even experienced developers who are new to a language or concept.
I've been teaching myself Rust in the past week and I've definitely noticed that, when I hit an error, a lot of library documentation assumes more depth of knowledge than I have right now. Say I want to know how to use a specific function and, beyond the quickstart, the docs are just a reference that keeps talking about Traits. I'm sure it'll click eventually, but right now, I just need to know how to call the function and fix the error I have!
Side note: I've rediscovered why Stack Overflow is so helpful as some of the answers there have helped me understand what's happening with different issues I run into!
This is how I feel trying to follow tutorials for using LLM or GenAI (LoRA, agentic, MCP what?)
Developers assuming way too much, in depth and in detail, is how you know they are a developer.
"Gee Rick, uh, I d-d-don't know if this tutorial is for real, I mean there's a bunch of random nonsense words and other stuff. I mean, is 'backside Snarfus stagnator' even a real thing?"
"Shut up Morty, you just don't unders-*buuurp*-tand what it takes to be a software engineer."
"Are you sure? What's a 'hoob-tunnel' and how does it get clogged with 'gramelions?' That just sounds like an improvised line from that sci-fi cartoon show..."
James Joyce would be proud of you, my friend. Great reading. Ditto the sentiments. Congrats!
I almost had a stroke trying to read this, now I get it. Thanks for the eye-opener.
False.
Nobody writes for beginners.
Beginners who hope to be Enders know this and so grok the whatits before whinging.
So basically, it is what you should be doing with users of your apps too
Ironic that 5 years from now we will yearn for the era of human-written tutorials.
You are right but the fact that it will be harder to distinguish between human written and AI written text means that we will be looking for signs that indicate a human written text and will tend to prefer humanly mistakes over AI perfect tutorial.
Yes. Before whining do your homework and learn about the concepts.
As a not-a-coder, this still rings true in way to many ways.
Thank God Snarfus is there, a reliable tool we use for years!
The title is misleading. Here is the actual title:
So, she is not a beginner developer, but a beginner at using your software.Whenever my team (cybersecurity) is about to send a global email or post, I wander around non technical teams to get 3 or 4 people to read it and explain me what it means.
Not once I got it right on first attempt. The final version was very different from the first one.
This is similar to the web page that was proposed to serve as the message people would read in case of a critical disaster of our systems.
The first version was with Vue, Tailwindcss and whatnot and I opened it on an old phone. Everything was everywhere, with drawers all over the place. I said that I would not approve anything beyond https://motherfuckingwebsite.com/ because I need it to work on a tomagoshi.
The version we have now is beautiful in its ugliness and clarity. It opens on a smart watch (well I don't know that actually :))
Nice how the blog is actually deved with ruby.
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 whole discussion in itself. If I remember correctly, the availability of training material for a technology already has slightly impacted more niche corners of the tech world.
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.
How do you think the LLMs train?
If I release a new library tomorrow, do I not need to write docs for it?
There not designed for beginners, but for peers.
I couldn't even understand what u had writter
Some tutorials require previous knowledge.
Straight from "A Clockwork Orange".
If you don't understand what is written, it's clearly not written for _you_. Same reason why whitepapers are not used as textbooks in high schools.
Jesus Christ. What kind of IDIOT tries to argyle the pintafore using hoobastank? Some "developer" this person is...
I literally said in the title I am not a developer but you’re right I should have known
Most devs write docs like aliens. Time to send them back to elementary school English class.
Most docs I read aren't written for an audience of non-developers.
Most docs I read aren’t written for any audience, imho.
That doesn't really excuse the strange acerbic brevity [that] I and most of my peers default to when writing technical documentation.
I like the term acerbic brevity! Generally though, I'd say concise and precise is exactly what I want in my docs, especially if I have to read hundreds of pages.
There's a fine line to walk for it to stay understandable though.
Academic papers sometimes take brevity to the extreme due to page limits and (frankly) bad writers, so much so that crucial parts are missing or ambiguous or where papers consist solely of formulas with little context.
Personally I draw the line where I need start writing down stuff in order to understand the following paragraphs. That's tedious.
However I encountered the other extreme too and it's similarly unbearable: full on conversational English in an overly friendly tone with everything explained at length and sometimes repeated. It gets old really quick and takes longer to get to what I need. Fine for a hobby project, but if I need it for work I don't want to spend time on that.
It's impatience and tiredness.
Taking an idea, and converting it into code is a lot of work. Taking that same idea and then taking the code and turning the both into words that can communicate the original idea is just another complex task. I'd wager that the dopamine hit of getting stuff working has worn off and most people are writing doco when they're exhausted from their recent work.
Conciseness is a feature.
So is thoroughness, you have to strike a balance.
Thank goodness it’s not just me. Had been assuming I was uniquely thick.
Skill issue.
This is gold
Pretty low effort as blog posts go.
Apparently it was so much more effort than she was willing to expend that she ended up just randomly banging on the keyboard ... and yet many here are treating this as some sort of serious criticism.
Accurate
I mean, if it reads like that, if probably wasn't meant for you. Which is fine, internet has a lot of content for the most obscure niches
Reminds me of an acronym that defines this sort of behaviour: COIK.
What is COIK? well everyone knows what COIK is, no need to bother explaining.
COIK is 'Clear Only If Known.' Did you really have to ask me about such a simple thing? Now run along.
____
There is so much assumed knowledge that writing guides becomes a matter of how simple you have to go, before you start insulting the reader's intelligence. (A computer is a magic box that goes DING!)
If you writing a guide, do you explain what a terminal is and where to find it? Or do you presume they know what it is and start sharing command lines? Is setting a minimum knowledge bar acceptable or are you showing your bias?
____
Obligatory XKCD:
https://xkcd.com/2501/
> sususudododo baby shark
Uh oh. I'm not sure if I'm going to be able to use `sudo` anymore.
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 from a completely different area of expertise. They shouldn't have to know what snarfus are, or how to fisterfunk the shamrock portal. In that case yes, let's mock the developer for completely missing the mark with a 6 paragraph long joke.
A beginner developer, however, is someone completely different. This is a person who will eventually have to juggle snarfus, and as unfortunate as it may be, even need to fisterfunk the shamrock portal. It is partially on them to put some effort into figuring out what fisterfunking is, and how it applies to the portal. If they are particularly good, after figuring out what those things are, they may even volunteer to update the documentation as to make it easier for the next beginner developer to understand it instead of replying with a 6 paragraph long joke about it.
FWIW, I submitted it as "non-developer" but a moderator seems to have changed it to "beginner developer."
The author is a non-technical blogger, and she probably has to navigate lots of technical guides in order to fiddle with her website or CSS. I think a more relevant discussion would be about making website publishing easier for everyday people, or about the lack of documentation written for that particular demographic. But HN took it in a different direction, which is fine.
> FWIW, I submitted it as "non-developer" but a moderator seems to have changed it to "beginner developer." The author is a non-technical blogger, and she probably has to navigate lots of technical guides in order to fiddle with her website or CSS. I think a more relevant discussion would be about making website publishing easier for everyday people, or about the lack of documentation written for that particular demographic. But HN took it in a different direction, which is fine.
That makes sense, thanks for clarifying. That's why made sure to point out the difference to avoid confusion. I think folks, including myself have been on all 3 sides of the situation: as a new developer who is supposed to learn confusing terminology, non-developer who is thrown a bunch of jargon to look at from a completely different domain that's not their responsibility, and the developer who write stuff and then wondered why other can't comprehend the "easy" tutorial.
This is an important clarification.
Checking out the homepage, Annie says her job is "content & documentation things", but also mentions CSS as a hobby, so I think it's a safe assumption this is the "non-professional hobby developer" niche which I think we'll see continue to grow.
It's a hard balance to get right. I've seen "install this tool" sort of tutorials which literally introduce the concept of opening a terminal and pressing Cmd+V and others which expect cron and Make knowledge as very basic table stakes. It's a wide variety!
I think if we're writing for an audience which will contain some amount of beginners or non-developers, it's maybe ~2min of effort to add a little collapsable (straight from Claude if you want) going into what exactly we mean by "cd into ~/.snarfus, creating it if it doesn't exist"
I donno. I remember being 13 trying to install Debian on my dad's old laptop. Any nuggets of knowledge helped.
> It's a hard balance to get right
Not really. With the wide availability of AI, you can dumb down almost any text to any any level you want.
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 your priority, in this case partial docs is better than no docs at all. But if your target is beginner developpers, imo you should consider them as non-developpers, as you correctly descibed them.
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/
SDZ should have been Heaven for me, but even as a teenager, I just couldn't get past the omnipresent enthousiasm and the smileys at the end of each sentence :)
:)
Guess I've always been grumpy.
Oh and yeah it's probably been enshittified nowadays, everything has. Wouldn't surprise me if they partnered with Ecole 42 to inundate the job market with programmers without degrees and drive the salaries down even more.
It says "me, a beginner"
The hn submitter presumably edited for length
By changing "non-developer" to "developer" (moving "beginner" from the end to the beginning doesn't really change the length). That's quite an intrusive change, it seems to me.
The edited one is longer. Why would you want to edit the title to make it longer?
No it isn't:
We are kind of both correct.
GP mentioned:
> 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
So GP cut off , a beginner ending which in turn falsified my claim of it being longer, and I didn't verify blog title.
My apologies, SoKamil, for cutting off the ending in the comparison. I wanted to highlight the difference and figured the first part is where the difference was. As in, they are still a non-developer and shouldn't have to learn all the details so it doesn't matter if they are just a regular non-developer a beginner non-developer.
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.
Also a lot of beginners skipped a lot of (cultural?) foundational knowledge. A basic understanding of filesystem, network, and os commands would go a long way for communication efficiency. Instead, they’re cargo-culting.
There really is a huge gap between a programmer and being capable at using a computer. I work in the data space and while im good enough for my own needs with Python and grew up in the 90s with MS-DOS and Windows 3.1/95, the second i have to use something that is build by and for programmers i too end up feeling like the blog post describes.
The difference is merely how this thing works vs how this thing is used. And the glue factor between the two is ops.
Between the developer and the user, there should be the maintainer role. Someone that took a software and make it run on a specific system. That requires familiarity with the system internal and build systems.
This is why packages managers like in linux distributions are a great solution. A working solution is often just a command away. App stores could be good too, if not for the gatekeeping effects.
> 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
For me the issue is some people expect everything to be simple/easy to do without any prior knowledge and then claiming it is not really hard but you are gatekeeping and only if you could explain it easier they would definitely grasp it instantly.
Also, it really depends on what the tutorial is about.
There's a difference between a tutorial on how to set up a wordpress on a shared hosting or how to add aditional debugging capability to kernel application core switching routines by patching the linux kernel.
In the first example, "unzip it" might need an additional explanation on how to do it in the command line... in the second,.. well... if you can't even unzip a file without the tutorial, you won't be able to use the software anyway.
In the end, lots of people who try to accomplish their goals writing some code don't see themselves as beginner developers but non-developers.
They just want to accomplish some well-defined and scoped task that happens to require some coding, but they have no interest, at least for now, on becoming developers.
oh come on please it's easy just /etc/init.apt-get/frob-set-conf --arc=0 - +/lib/syn.${SETDCONPATH}.so.4.2 even my grandma can do that
You forgot the “welcome to Linux!”
Just confirming, I've seen that the title between the post and link are inconsistent incase there's any confusion.
While I agree, the difference is significant, and it is often the case that a a decent tutorial/blog post on a technology is rarely tailored to non developers
I do think there's a kernel of truth in this for with educational content written by developers. I think many developers underestimate the attention and care that's necessary to write high quality education material. Not to say they shouldn't, it's a valuable skill for everyone to develop but it doesn't always come naturally.
I think one part of it is, in writing the content sometimes someone who is inexperienced in writing, might be writing something with dual roles in mind. They may be venting their frustrations with learning the technology, selling their experience and accomplishments (to any potential employers who may be reading it, which is where some name dropping might be coming in) and using the format of a tutorial as a vehicle to do so. They may also just not have a clear objective of what they want to write in mind and they just want to share some information and they initially wrote a tutorial and veered off on to something else.
If you're someone who is reading something like this, it can actually be annoying or confusing if you went into the tutorial expecting one thing which doesn't end up being there. For a beginner even more so, as you lack the domain knowledge to know if you need to disregard these tangents or skip forward, if you're more experience it feel like someone is wasting your time by telling you they were going to explain X Y Z then it ends up being some rant passing as a half baked tutorial. That said I rather this than AI slop, but reading it can be equally annoying if it feels like the author doesn't respect your time in the way AI slop feels like there's an expectation your time reading it is worth less than the time the author would spent writing it.
The issue here for the reader is usually the content is inconsistent with their expectations, and for the author they possible communicated that poorly.
Yes if the author has mistakenly assumed an article not written for them were written for them, well yes that's on the author. But taking what they say at face value or even the title used at the post I think there is a point of value to take away from this for those writing anything ranging from education material to a post mortem.
Know your objective, the key information your communicating, has the way you've written effectively communicated that to your intended audience? Cull things that detract from this. And of course there's nothing wrong with unstructured forms of writing, they can be really fun, but they are the last thing someone wants to read when they are in the middle of trying to fix a technical issue they don't entirely understand. That can largely be avoided by with a better title, or avoiding insinuating the post is something it's not.