14 ms·

How I, a non-developer, read the tutorial you, a developer, wrote for me

• ivanjermakov 1y ago
  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.
• 01HNNWZ0MV43FF 1y ago
  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.
• poppobit 1y ago
  Most devs write docs like aliens. Time to send them back to elementary school English class.
  • bigyabai 1y ago
    Most docs I read aren't written for an audience of non-developers.
    • ShroudedNight 1y ago
      That doesn't really excuse the strange acerbic brevity [that] I and most of my peers default to when writing technical documentation.
      • gonzo41 1y ago
        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.
      • jval43 1y ago
        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.
      • goodpoint 1y ago
        Conciseness is a feature.
        • mnbpdx 1y ago
          So is thoroughness, you have to strike a balance.
    • aaronbrethorst 1y ago
      Most docs I read aren’t written for any audience, imho.
• Johnny_Bonk 1y ago
  This is gold
• Swizec 1y ago
  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.
  • bsder 1y ago
    > 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.
    • chickenzzzzu 1y ago
      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.
      • all2 1y ago
        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.
• shmerl 1y ago
  The funniest part, lol it might be in library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam.file.
  • Nition 1y ago
    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.
  • ViscountPenguin 1y ago
    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
  • mirekrusin 1y ago
    sususudododo baby shark ...looks scary as well in hands of inexperienced.
    • shmerl 1y ago
      That is true, especially when instructions are spooky like curl blah-blah | sh And people run that without thinking.
  • 1718627440 1y ago
    bash: cd: too many arguments
• groovetandon 1y ago
  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.
  • beefnugs 1y ago
    Yeah, this poor guy stumbling around the internet who should be reading kids books keeps clicking on kubernetes how-tos
• evanjrowley 1y ago
  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.
  • card_zero 1y ago
    Not emulator, emulater. This technical term may also hyphenated, emu-later.
    • cheschire 1y ago
      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.
  • ShroudedNight 1y ago
    Oh please, this is why it's _clearly_ superior to run Catenary or P. Papua
  • qnleigh 1y ago
    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.
    • 1y ago
• NoteyComplexity 1y ago
  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.
  • chickenzzzzu 1y ago
    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.
  • a96 1y ago
    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.
• maplethorpe 1y ago
  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.
  • 01HNNWZ0MV43FF 1y ago
    That is the typical experience for C++ tooling lol
    • chickenzzzzu 1y ago
      C++ is written by 99% professional architecture astronauts who do fuck all in terms of valuable software. I will die on this hill.
      • acuozzo 1y ago
        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.
        • chickenzzzzu 1y ago
          The language committee only makes it harder and more astronauty every year. How many Unreal Engine developers from 2007-2013 understand CPP20/23?
          • Arainach 1y ago
            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.
          • 1y ago
• onion2k 1y ago
  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,
  • acuozzo 1y ago
    > 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.
    • jrs235 1y ago
      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)?
      • peterfirefly 1y ago
        That can also easily be misconstrued.
  • ShroudedNight 1y ago
    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.
• windex 1y ago
  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.
• saurik 1y ago
  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.
  • peteforde 1y ago
    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.
• renewiltord 1y ago
  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.
• csallen 1y ago
  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.
  • jiggawatts 1y ago
    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.
    • 1y ago
• pjdesno 1y ago
  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.
  • yakshaving_jgt 1y ago
    Ironically, online recipes of the cookbook kind are actually much worse for meandering and irrelevant prose than programmer blogs are.
• jrue 1y ago
  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.
  • yakshaving_jgt 1y ago
    Indeed, if the author had added this code sample, it all would have been clear. f←{⍸≠⌈\(⍴∘∪⊢∨⍳)¨⍳⍵} --- Said in light-hearted jest, and not in sarcasm
• scuff3d 1y ago
  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.
• kushie 1y ago
  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.
• peteforde 1y ago
  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/ https://diataxis.fr/ is a really solid starting point for anyone aspiring to create better docs.
  • gertlex 1y ago
    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.)
    • devoutsalsa 1y ago
      Lately I’ve been asking Cursor “what does the program do?” Was actually pretty helpful as a starting point.
      • gertlex 1y ago
        Oh yeah, definitely. Great for my own "throwaway" or rushed projects that I want to revisit, too :D
• nomilk 1y ago
  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.
  • euroderf 1y ago
    Ask the guinea pig (read: victim) also to think aloud.
  • BiteCode_dev 1y ago
    Basically, ergonomic testing, but for your doc instead of your software.
  • Our_Benefactors 1y ago
    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.
  • fragmede 1y ago
    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.
• rimmontrieu 1y ago
  This mirrors my experiences 20 years go, but I actually appreciated it because it pushed me harder to learn the dev arcane languages.
• protocolture 1y ago
  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.
  • a96 1y ago
    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.
• dr__mario 1y ago
  Straight from "A Clockwork Orange".
• auggierose 1y ago
  The title is misleading. Here is the actual title: "How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner" So, she is not a beginner developer, but a beginner at using your software.
• ChrisMarshallNY 1y ago
  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 https://littlegreenviper.com/miscellany [1] https://littlegreenviper.com/leaving-a-legacy/ https://littlegreenviper.com/leaving-a-legacy/
• deleted 1y ago
  [deleted]
• deleted 1y ago
  [deleted]
• rdtsc 1y ago
  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.
  • f33d5173 1y ago
    It says "me, a beginner" The hn submitter presumably edited for length
    • deleted 1y ago
      [deleted]
    • SoKamil 1y ago
      The edited one is longer. Why would you want to edit the title to make it longer?
      • card_zero 1y ago
        No it isn't: 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
• seemaze 1y ago
  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!
• PeterStuer 1y ago
  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.
• pessimizer 1y ago
  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.
• montgomery_r 1y ago
  Thank goodness it’s not just me. Had been assuming I was uniquely thick.
• tiku 1y ago
  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.
• jibal 1y ago
  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).
  • NetMageSCW 1y ago
    That was the analysis of an actual tutorial.
    • jibal 1y ago
      Oh? Which one?
      • jibal 1y ago
        In other words: No it wasn't, and you know it wasn't. There's word for that.
  • annienotadev 1y ago
    Good observation. Silly is the point. You nailed it.
    • jibal 1y ago
      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.
• deleted 1y ago
  [deleted]
• nenenejej 1y ago
  > 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?
• fergie 1y ago
  Ironic that 5 years from now we will yearn for the era of human-written tutorials.
  • Waraqa 1y ago
    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.
• abhishekbr 1y ago
  I couldn't even understand what u had writter
• InsideOutSanta 1y ago
  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.
• globular-toast 1y ago
  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."
• harvey9 1y ago
  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.
• oytis 1y ago
  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
• dncornholio 1y ago
  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.
• general1465 1y ago
  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.
• rtodea 1y ago
  This reminds me of the Rockwell Retro Encabulator[1]. I understand the frustration. [1] https://www.youtube.com/watch?v=RXJKdh1KZ0w https://www.youtube.com/watch?v=RXJKdh1KZ0w
  • imrejonk 1y ago
    I was thinking about the same thing. Such a classic!
• dayvster 1y ago
  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.
• arkh 1y ago
  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.
• poisonborz 1y ago
  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.
  • tsm 1y ago
    How do you think the LLMs train? If I release a new library tomorrow, do I not need to write docs for it?
  • creesch 1y ago
    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.
    • poisonborz 1y ago
      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.
      • creesch 1y ago
        Given it has been a few days it might be unlikely that you read it. But I figured I'd reply anyway in case you do. I mean this with no hostile intend, but have you honestly stopped and thought about what you did type down here? What I mean by that is, have you looked at the complete picture to see if what you are saying makes sense in relation to what you initially said. You questioned the need for documentation. Now you are saying there needs to be good documentation for LLMs to train on. Good documentation for LLMs to train on is actually much more extensive than than the documentation written for humans to begin with. So, you are effectively saying there needs to be more documentation. Secondly, how can developers ask about something when they don't have decent documentation to start with.
• kepeko 1y ago
  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.
  • mike_hearn 1y ago
    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/python-api/class/WheeledVehiclePawn?highlight=chaoswheeledvehicle&application_version=5.0 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.
• constantcrying 1y ago
  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.
• scott_w 1y ago
  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!
• creesch 1y ago
  I am surprised nobody mentioned the curse of knowledge: https://en.wikipedia.org/wiki/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.
• yoz-y 1y ago
  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.
• wraptile 1y ago
  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.
  • ArcHound 1y ago
    Hello, I am just now trying to upgrade my blog. Can you please point me to sites that do this right?
    • taink 1y ago
      An extreme example would be gwern.net -- specifically you might want to read https://gwern.net/about https://gwern.net/about and https://gwern.net/design https://gwern.net/design
      • ArcHound 1y ago
        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.
• nottorp 1y ago
  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?
• addandsubtract 1y ago
  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.
• timwis 1y ago
  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.
• rob_c 1y ago
  "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...
• thorum 1y ago
  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.
  • NetMageSCW 1y ago
    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.
• Vinnl 1y ago
  > sususudododo baby shark Uh oh. I'm not sure if I'm going to be able to use `sudo` anymore.
• palata 1y ago
  If you can't understand half the words, you're not the target audience, period.
• UK-Al05 1y ago
  There not designed for beginners, but for peers.
• oldestofsports 1y ago
  Honorable mention: https://youtu.be/aW2LvQUcwqc?si=IqPtgd3cxpUKwWRm https://youtu.be/aW2LvQUcwqc?si=IqPtgd3cxpUKwWRm
• erikbye 1y ago
  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.
• alex-moon 1y ago
  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/ https://mkyong.com/tutorials/spring-tutorials/
• beklein 1y ago
  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.
  • aDyslecticCrow 1y ago
    > 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.
    • AlienRobot 1y ago
      "What is an exe?"
  • Kneecaps07 1y ago
    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.
• pSYoniK 1y ago
  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.
  • teekert 1y ago
    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.
    • NetMageSCW 1y ago
      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.
• eviks 1y ago
  > 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
  • ezfe 1y ago
    good job, you missed the point
    • eviks 1y ago
      Great job, you've failed to document the point.
      • NetMageSCW 1y ago
        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.
        • eviks 1y ago
          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.
      • ezfe 1y ago
• ratmeadow 1y ago
  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-doing https://mc-deltat.github.io/articles/what-the-f-is-this-code...
• itomato 1y ago
  False. Nobody writes for beginners. Beginners who hope to be Enders know this and so grok the whatits before whinging.
• deleted 1y ago
  [deleted]
• entelechy0 1y ago
  [dead]
• zvmaz 1y ago
  It's not just programming tutorials, but it's a phenomenon that is widespread [1]. [1] https://en.wikipedia.org/wiki/Curse_of_knowledge https://en.wikipedia.org/wiki/Curse_of_knowledge
• voxleone 1y ago
  James Joyce would be proud of you, my friend. Great reading. Ditto the sentiments. Congrats!
• econ 1y ago
  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.
  • phil294 1y ago
    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.
    • econ 1y ago
      So be it? An additional thought I had was that new tools can have awesome discoverability in a webdirectory of tutorials. Normally the more exotic the creature the better it hides. We could be publishing a lot of things that could be great for an audience near zero. It wouldn't even need an awesome name to point at, just the right location in the right tutorial(s). If llms are to do it we could probably have it make videos too. I want Derek Banas on the project.
• wosined 1y ago
  Some tutorials require previous knowledge.
• geldedus 1y ago
  Yes. Before whining do your homework and learn about the concepts.
• 1970-01-01 1y ago
  Developers assuming way too much, in depth and in detail, is how you know they are a developer.
• dmd 1y ago
  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
  • NetMageSCW 1y ago
    You forgot the “welcome to Linux!”
• BrandoElFollito 1y ago
  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/ 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 :))
• sylens 1y ago
  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"
  • lptome 1y ago
    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.
• heelix 1y ago
  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.
• kunley 1y ago
  Thank God Snarfus is there, a reliable tool we use for years!
• virajk_31 1y ago
  I almost had a stroke trying to read this, now I get it. Thanks for the eye-opener.
• paddy_m 1y ago
  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.
  • NetMageSCW 1y ago
    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.
• kunley 1y ago
  Next time I won't forget to improve my life by running sususudododo baby shark on a regular basis.
• the__alchemist 1y ago
  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.
• dizhn 1y ago
  Pretty low effort as blog posts go.
  • annienotadev 1y ago
    Accurate
  • jibal 1y ago
    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.
• k__ 1y ago
  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.
• gwbas1c 1y ago
  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.
• emilecantin 1y ago
  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.
• OJFord 1y ago
  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.
• pwdisswordfishz 1y ago
  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.
• tonmoy 1y ago
  This is how I feel trying to follow tutorials for using LLM or GenAI (LoRA, agentic, MCP what?)
• nobodyandproud 1y ago
  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.
• philipwhiuk 1y ago
  > 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.
• magic_hamster 1y ago
  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.
  • zahlman 1y ago
    > 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.
• CarpeQueso 1y ago
  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.
• MarkusWandel 1y ago
  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.
  • officehero 1y ago
    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.
• daniel-gerow 1y ago
  As a not-a-coder, this still rings true in way to many ways.
• EGreg 1y ago
  So basically, it is what you should be doing with users of your apps too
• stevenicr 1y ago
  Makes me want to revisit my (started, but not posted) screenshots and videos of trying to install matrix / element following the random directions / docs.
• Rooster61 1y ago
  Jesus Christ. What kind of IDIOT tries to argyle the pintafore using hoobastank? Some "developer" this person is...
  • annienotadev 1y ago
    I literally said in the title I am not a developer but you’re right I should have known
• i-chuks 1y ago
  Nice how the blog is actually deved with ruby.
• ctrlp 1y ago
  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.
• fnordlord 1y ago
  Thanks for this. I never knew how much I'd like it if George Saunders started a tech blog.
  • annienotadev 1y ago
    Omg this is high praise I’ll never be able to write anything again
• thomastjeffery 1y ago
  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.
• lacoolj 1y ago
  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.
• peterfirefly 1y ago
  Skill issue.
• bluecheese452 1y ago
  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.
• tonymet 1y ago
  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.
• ayaros 1y ago
  "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..."
• beeboop0 1y ago
  [dead]
• Dementor430 1y ago
  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...
  • annienotadev 1y ago
    OPs everything is flawed but she tries really hard.
    • jibal 1y ago
      If this is you trying really hard ...
    • Dementor430 1y ago
      nice alt
• GarnetFloride 1y ago
  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.
• akst 1y ago
  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.
• annienotadev 1y ago
  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
• turtleyacht 1y ago
  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.
• ryzvonusef 1y ago
  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/ https://xkcd.com/2501/
• papanoah 1y ago
  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.
• c0ax9 1y ago
  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)