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.
Nargflargler: Flargles the narg
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).
I've basically resigned myself to "it makes sense in Redmond somehow, even if it makes no sense to me."
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.
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.
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
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.
setFontSize(float): sets the font size.
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
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
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.
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".
A structure that defines a metadata key space.
source: https://developer.apple.com/documentation/avfoundation/avmet...
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...
There’s plenty of other poorly documented Apple APIs (io_surface), but this isn’t one of them.
Sounds like something that should be mentioned in the opening sentence of https://developer.apple.com/documentation/avfoundation/avmet...
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.
Going off to read the header file means it isn't documented.
I have to assume that there exists some language where that relationship is described in one word, but it hurts my English-oriented brain.
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.
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.
> A prepositional phrase is a phrase with a preposition in it.
> A preposition is a word in a prepositional phrase.
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
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.
Lives rent free in my brain.
dont say.. boop?!
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.
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.
> 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.
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.
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.
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.
>> 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.
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.
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.
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.
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.
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
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.
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 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).
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.
> Users don’t have the manual, and if they did, they wouldn’t read it.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.
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.
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"...
Fixing and updating the README when I join a new team and set up their dev environment is always extremely well-received.
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.
It saved me a whole bunch of headaches for when other users get enrolled in these workflows.
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.
Okay, but GP is talking about tutorials, which are a completely different form of documentation.
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?
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).
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.
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.
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.
> Those are references, not tutorial.
But as library users, we're generally not supposed to have to learn the system from its source, aren't we?
... 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.
An important point easy to lose sight of when writing when that knowledge isn't lost yet
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.
The golden rule: Plan -> Act -> Test -> Repeat
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?
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
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.
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.
> never be able to grow in their role and move up to tier 2. I'm not sure how to solve for this problem.
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.
Watch someone play the game for the first time. Don’t interfere. See if they can figure out how to play.
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.
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.
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.
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.
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.
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.
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"
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'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.
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'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.
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.
Personally I'm not a big fan of copious extensions. I use them some times but I'd describe my usage as sparingly.
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.
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)
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.
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.
Static methods are useful for namespacing, e.g.
var instance = SomeThing.fromString("...")
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.
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.
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
If you want to teach algorithmic thinking, teach Python.
If you want to teach hardware and low-level systems, teach C.
> I think Java is dying.
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
.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 can't see any reason to choose node for typical backend programming and such unless your devs only know JS.
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?
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.
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?
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!
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)
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
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.
Examples are often the best way to do documentation, sadly.
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.
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.
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.
But I'm pretty sure it's universal, like you allude to. And not just open-source; but at work, too. I feel like I'm the only one in my company that makes PRs to edit the READMEs to explain what a repo is for, and what repos it might relate to. (I was much happier in the past when we had a couple mono-repos; now the trend is every little project gets its own undocumented repo, alas.)
Oftentimes when the tool is typically used as part of a useful stack, the other components have documentation that can also be difficult to decode. So it becomes an order of magnitude more difficult to understand.
I can read the code, I can understand how it works but I cannot know why you decided to tackle this issue a certain way.
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.
Those raids are like herding cats. Distracted, teenage cats with connectivity issues.
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,
While sharing may be better than assuming when only considering the local optimum, if your signal to noise ratio is bad enough, you will face an impairment to communication that simply wouldn't exist if you had been more selective.
Definitely agree with this in principle. My son and I play pool (billiards) competitively. As you get better, almost nobody shares any tips because it's very competitive. I've taught him to be better than that and we have a great league team where everyone is helping the others grow.
In the mentoring (not just teaching) realm, I like to guide them into asking the questions that gets them to the answer they're looking for. When the connections in their mind light up, it's amazing.
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.
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 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.
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'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.
Knowing where to jump in your stack is a tricky question, though.
Integrating with Linux/Windows display surfaces is disgusting however. KMSDRM is way, way better than the nightmare that is X11 and Wayland.
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.
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 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).
This is very different from bad documentation or writing.
Not everything should be reduced to eli5.
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.
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.
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?
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!
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.
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"
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.
With that being said, it is (and has been) used to produce valuable software.
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.
I hope you don't die on a hill tho, not anytime soon at least.
EDIT: thank you for your well wishes though :)
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.
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.
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.
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.
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.
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.
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.
f←{⍸≠⌈\(⍴∘∪⊢∨⍳)¨⍳⍵}
Said in light-hearted jest, and not in sarcasm
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.
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.
—Annie, not a dev
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.
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.
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.
At least the beginner perspective captured enthusiasm, empathy (an alternative error condition for a path to a hidden file), and the request for feedback.
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.
It's their first contribution to our code base.
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.
`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.
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.
[1] https://mc-deltat.github.io/articles/what-the-f-is-this-code...
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.
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.
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...
Needless to say she signed up for a professional course, got the license, and we’ve travelled nearly 10,000 miles together since!
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.
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.
Even the submitter must have realized this, which is why they changed the title.
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.
All docs should start with examples. Some docs would be better if they ended right there.
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.
> 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.
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.
Except in most real cases you're following the tutorial for, where it is both mandatory and non-obvious it's not been done.
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.
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.
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
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.
"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 left that company, and left a letter for management about the abysmal developer experience.
Is that format better or worse than the SEO tutorials that spend half the time explaining what a conditional statement or a loop is?
it might be in library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam.file. sususudododo baby shark
curl blah-blah | sh
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.
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!
"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..."
Nobody writes for beginners.
Beginners who hope to be Enders know this and so grok the whatits before whinging.
"How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner"
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 :))
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.
If I release a new library tomorrow, do I not need to write docs for it?
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.
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:
Uh oh. I'm not sure if I'm going to be able to use `sudo` anymore.
> 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.
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.
Not really. With the wide availability of AI, you can dumb down almost any text to any any level you want.
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 always assumed it meant "a website for 'zeros'" as in "complete noobs"
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/
:)
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.
The hn submitter presumably edited for length
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 meGP 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.
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.
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.
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.
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.
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.
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.