5 ms·

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 communica

by 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.
lukan 1y ago
"Most tutorials are not for non-developers" That has been repeated in the comments many times now, but the very headline says that this tutorial was indeed also intended for non developers. Like some open source Github project that the author merely wanted to install, not starting to mess with the code. Basically, it is complaining in a satirical way about installation readmes, that maybe they could be made easier, that also non developers can follow some simple steps. A complaint that I can very much agree with, even though I am a developer. But so often little steps are left out and when that happens in a area you are not familiar with, then this can mean lots of wasted hours.
- Swizec 1y ago
  > it is complaining in a satirical way about installation readmes, that maybe they could be made easier, that also non developers can follow some simple steps See I missed that context :D Installation readmes are an interesting example – they shouldn’t exist. Put that effort in an install script instead. If you want me to mechanically follow some steps, perhaps with a decision tree attached … computers are really good at that!
  - beeflet 1y ago
    The install script may not have all the context it needs to be installed. In the long run it is better to teach the user how your software works in plain english. Even in projects with an install script, for example pmbootstrap, the install script also needs a tutorial. In my experience, projects with minimal documentation and an install script will have the the install script fail halfway through because it assumed something about my system that isn't true, or it will do something incredibly insecure like requesting su and then curl | bash
  - 1718627440 1y ago
    The installation readme generally tells you how to invoke the install script that does all the really complicated stuff.
- lintfordpickle 1y ago
  > "That has been repeated in the comments many times now, but the very headline says that this tutorial was indeed also intended for non developers" tbf, that's not how I read the headline. The headline is: "How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner" The author is a beginner, which puts them in the field - so the parent comment is valid no?
marklubi 1y ago
> Beginners have to be nurtured through lots of context that builds up slowly. My son is 17 and very interested in programming. Had to explain to him public, private, internal, and also static the other night. I then joked, you should ask your teacher about recursion tomorrow. He's with his mom this weekend, but I'm anxiously awaiting hearing how that went.
- devjab 1y ago
  > Had to explain to him public, private, internal, and also static the other night. Access modifiers are sort of a dying breed in a lot of places aren't they? We use Go, so we're obviously still using the two it comes with, but it's public vs module only and fairly intuitive. Every other language we have in production, doesn't make use of access modifiers. Similarily while static is a thing in Python, it's hard to see what advantages it brings compared to a free function if you're using a programming language that doesn't require you to have object instances to call non-static functions. Obviously access modifiers will stick around in a lot of organisations, but there will be plenty of jobs where you never have to work with them. The way Go handles modules, is frankly one of the few language feature of any language I've ever worked with that I wish was in every language I work with. It's so easy to use and so hard to mess up. Ok, I guess it's not hard to mess it up, but it's not intuitive.
  - marklubi 1y ago
    Not going to disagree. It's the sandbox that we're playing in though (dealing with, HOORAY JAVA!) since it's a class at school. Have to start somewhere, teach them better alternatives as they evolve. Not even going to broach the prototype-based programing stuff until he comfortably has the basics understood. Edit: I don't GAF about downvotes, but I would at least expect a response about why. If you don't like the philosophy, give me some reasons. Don't like something else, tell me why. I'll happily debate anyone all day long
  - mike_hearn 1y ago
    Access modifiers are useful, albeit not for beginners. They're most useful in statically typed languages with good tooling where they keep auto-generated API docs and autocompletions clean. Static methods are useful for namespacing, e.g. var instance = SomeThing.fromString("...") In some languages you can of course make a global free function called someThingFromString which does the same thing, but then (a) it won't have access to private methods so the public API surface gets more polluted with stuff the user maybe shouldn't call themselves, and (b) it won't show up in the right place in generated API docs and (c) it won't show up in the expected place in type autocompletion. Kotlin has both static methods (or rather companion objects which are an equivalent), and also top level free functions, and when writing it I find myself creating static methods a lot more often for the above reasons.
noufalibrahim 1y ago
> Beginners have to be nurtured through lots of context that builds up slowly. I agree and when I write for such an audience, I try to be detailed and build on a proper story that they can follow through. I do have a complaint about attempts to smoothen the DX which a lot of projects do that results in something which helps only the absolute beginner. Logs are not easily accessible or missing. It's not easy to cut/paste or grep for errors in things etc. Basically, many of of the familiar tools and techniques which people have used to find their way through things are replaced by poor substitutes in the name of making the DX better. This, I don't think is a good trend.
karaterobot 1y ago
I guess I disagree that it's a good thing. As a developer, I think most documentation is terrible both for developers and non-developers alike. And if you write your documentation so that it is useful to non-developers, it's still useful for developers. There's no downside to writing accessible documentation, except that it requires a modicum of skill and effort. That's the real reason it's so rare, I think. I also disagree that developer documentation is like academic papers. The ways they fail are almost opposite: academic papers are overly long and overwritten, because the authors want to be very careful and complete. Developer documentation is too short and hastily written, because they often don't care if it's helpful to anybody else. The end result may be the same: neither are useful except to a small number of experts: the people who could probably do it themselves already, and thus may not even really need the write up to begin with. But that's a failure, not a feature to be celebrated.
godelski 1y ago
> They’re more like academic papers (peer-to-peer communication of new discoveries) This made me laugh because I frequently see HN comments on arxiv papers claiming things like the authors are trying to show off with their math rather than the math just being an effective communication tool. Honestly, if anything, papers are written to too broad of an audience and we get these 10 page papers that could be communicated in 3. I'm unsure if this has been a good change. (Yes, I read the whole comment) Just because you have access to the text doesn't mean you're the intended audience. Probably a good thing for us to all remember here on the interwebs where everything is accessible but written for no one

by Swizec 1y ago

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.

lukan 1y ago

"Most tutorials are not for non-developers" That has been repeated in the comments many times now, but the very headline says that this tutorial was indeed also intended for non developers. Like some open source Github project that the author merely wanted to install, not starting to mess with the code. Basically, it is complaining in a satirical way about installation readmes, that maybe they could be made easier, that also non developers can follow some simple steps. A complaint that I can very much agree with, even though I am a developer. But so often little steps are left out and when that happens in a area you are not familiar with, then this can mean lots of wasted hours.

Swizec 1y ago
> it is complaining in a satirical way about installation readmes, that maybe they could be made easier, that also non developers can follow some simple steps See I missed that context :D Installation readmes are an interesting example – they shouldn’t exist. Put that effort in an install script instead. If you want me to mechanically follow some steps, perhaps with a decision tree attached … computers are really good at that!
- beeflet 1y ago
  The install script may not have all the context it needs to be installed. In the long run it is better to teach the user how your software works in plain english. Even in projects with an install script, for example pmbootstrap, the install script also needs a tutorial. In my experience, projects with minimal documentation and an install script will have the the install script fail halfway through because it assumed something about my system that isn't true, or it will do something incredibly insecure like requesting su and then curl | bash
- 1718627440 1y ago
  The installation readme generally tells you how to invoke the install script that does all the really complicated stuff.
lintfordpickle 1y ago
> "That has been repeated in the comments many times now, but the very headline says that this tutorial was indeed also intended for non developers" tbf, that's not how I read the headline. The headline is: "How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner" The author is a beginner, which puts them in the field - so the parent comment is valid no?

marklubi 1y ago

> Beginners have to be nurtured through lots of context that builds up slowly. My son is 17 and very interested in programming. Had to explain to him public, private, internal, and also static the other night. I then joked, you should ask your teacher about recursion tomorrow. He's with his mom this weekend, but I'm anxiously awaiting hearing how that went.

devjab 1y ago
> Had to explain to him public, private, internal, and also static the other night. Access modifiers are sort of a dying breed in a lot of places aren't they? We use Go, so we're obviously still using the two it comes with, but it's public vs module only and fairly intuitive. Every other language we have in production, doesn't make use of access modifiers. Similarily while static is a thing in Python, it's hard to see what advantages it brings compared to a free function if you're using a programming language that doesn't require you to have object instances to call non-static functions. Obviously access modifiers will stick around in a lot of organisations, but there will be plenty of jobs where you never have to work with them. The way Go handles modules, is frankly one of the few language feature of any language I've ever worked with that I wish was in every language I work with. It's so easy to use and so hard to mess up. Ok, I guess it's not hard to mess it up, but it's not intuitive.
- marklubi 1y ago
  Not going to disagree. It's the sandbox that we're playing in though (dealing with, HOORAY JAVA!) since it's a class at school. Have to start somewhere, teach them better alternatives as they evolve. Not even going to broach the prototype-based programing stuff until he comfortably has the basics understood. Edit: I don't GAF about downvotes, but I would at least expect a response about why. If you don't like the philosophy, give me some reasons. Don't like something else, tell me why. I'll happily debate anyone all day long
- mike_hearn 1y ago
  Access modifiers are useful, albeit not for beginners. They're most useful in statically typed languages with good tooling where they keep auto-generated API docs and autocompletions clean. Static methods are useful for namespacing, e.g. var instance = SomeThing.fromString("...") In some languages you can of course make a global free function called someThingFromString which does the same thing, but then (a) it won't have access to private methods so the public API surface gets more polluted with stuff the user maybe shouldn't call themselves, and (b) it won't show up in the right place in generated API docs and (c) it won't show up in the expected place in type autocompletion. Kotlin has both static methods (or rather companion objects which are an equivalent), and also top level free functions, and when writing it I find myself creating static methods a lot more often for the above reasons.

noufalibrahim 1y ago

> Beginners have to be nurtured through lots of context that builds up slowly. I agree and when I write for such an audience, I try to be detailed and build on a proper story that they can follow through. I do have a complaint about attempts to smoothen the DX which a lot of projects do that results in something which helps only the absolute beginner. Logs are not easily accessible or missing. It's not easy to cut/paste or grep for errors in things etc. Basically, many of of the familiar tools and techniques which people have used to find their way through things are replaced by poor substitutes in the name of making the DX better. This, I don't think is a good trend.

karaterobot 1y ago

I guess I disagree that it's a good thing. As a developer, I think most documentation is terrible both for developers and non-developers alike. And if you write your documentation so that it is useful to non-developers, it's still useful for developers. There's no downside to writing accessible documentation, except that it requires a modicum of skill and effort. That's the real reason it's so rare, I think. I also disagree that developer documentation is like academic papers. The ways they fail are almost opposite: academic papers are overly long and overwritten, because the authors want to be very careful and complete. Developer documentation is too short and hastily written, because they often don't care if it's helpful to anybody else. The end result may be the same: neither are useful except to a small number of experts: the people who could probably do it themselves already, and thus may not even really need the write up to begin with. But that's a failure, not a feature to be celebrated.

godelski 1y ago

> They’re more like academic papers (peer-to-peer communication of new discoveries) This made me laugh because I frequently see HN comments on arxiv papers claiming things like the authors are trying to show off with their math rather than the math just being an effective communication tool. Honestly, if anything, papers are written to too broad of an audience and we get these 10 page papers that could be communicated in 3. I'm unsure if this has been a good change. (Yes, I read the whole comment) Just because you have access to the text doesn't mean you're the intended audience. Probably a good thing for us to all remember here on the interwebs where everything is accessible but written for no one