4 ms·

I take a different approach in technical materials I write. I want to make system internals accessible to more people, not to a restricted few who have the righ

I take a different approach in technical materials I write. I want to make system internals accessible to more people, not to a restricted few who have the right prior knowledge. I try to write something that everyone understands who has a minimal relevant background (i.e. everyone who would be interested in reading the post) but include links to deeper materials or kernel source code so that everyone can learn from it. Here's an example with an article I wrote on Linux shebangs: https://natanyellin.com/posts/shebang-python-bad-interpreter-m/ https://natanyellin.com/posts/shebang-python-bad-interpreter... Would love to hear constructive criticism on how I can improve!

mjburgess 5y ago
What's linux? What's python? What's a script? What's a kernal? What's a symlink? What's hex? What's a hex-editor? i_end = strnchr(bprm->buf, sizeof(bprm->buf), '\n'); What's `->buf`, `strnchr(bprm`, `sizeof(brmp`, ? Why does `\n';` have a `;` ? FYI: I know the answers to all these questions but the idea that this article isnt for a "restricted few who have the right prior knowledge" is bizarre. It reads almost like a satire... this would be a classic case of an article where a vast amount of prior knowledge is presumed. Who knows what a kernal is that doesnt know how to debug `/usr/local/bin/python^M` ? Some, but a vanishingly small highly priorly knowledable group.
- nyellin 5y ago
  First of all, thank you for the comments. That said, I'm not claiming that you don't need any pre-requisites. Obviously this article is aimed at people who use bash or else they wouldn't be having an issue with the shebang! There is a huge audience who knows what a kernel is (in theory) and writes shell scripts, but doesn't know how shebangs work and has never actually looked at kernel code. My point isn't that you don't need prerequisites, rather that I think there is room for writing at a certain level while also giving people hooks to learn more. Anyway, I do appreciate the feedback. Thank you.
Beltalowda 5y ago
Let's say you have a book about a programming language; writing this in a way that anyone can follow – even those have never programmed before – would substantially increase the size of the book, as well as make it harder to follow for more experienced readers, since they will need to cut through all the stuff explaining the basics (loops, types, variables, etc.) in ways that a beginner can understand to get at the stuff they're actually interested in. Your approach works well for fairly short/simple concepts (although even in your article, there's a lot of assumed knowledge), but it gets harder the longer or more deep the content becomes. As for the posted article, I never had this problem. I suspect the author just bought badly written books; there are many of those, unfortunately.
k__ 5y ago
So, you say you write for "everyone who has a minimal relevant background" can read this. What does this even mean it the case of the article? The minimal relevant background is that you know how to copy a Python script with an \r to a Linux machine. This includes Python developers, for which this article is written. But it also includes non-Python developers. In fact, this even includes everyone who wants to run a Python script on a Linux machine. Administrators, but even regular users without much technical knowledge. So, our reader persona is the average Linux user. If I look at that article from the perspective of this persona, at least 80% of it doesn't help me at all. The article should start with the fix, and not redirect the reader to the end of the article.
- nyellin 5y ago
  Good point. Thank you.

mjburgess 5y ago

What's linux? What's python? What's a script? What's a kernal? What's a symlink? What's hex? What's a hex-editor? i_end = strnchr(bprm->buf, sizeof(bprm->buf), '\n'); What's `->buf`, `strnchr(bprm`, `sizeof(brmp`, ? Why does `\n';` have a `;` ? FYI: I know the answers to all these questions but the idea that this article isnt for a "restricted few who have the right prior knowledge" is bizarre. It reads almost like a satire... this would be a classic case of an article where a vast amount of prior knowledge is presumed. Who knows what a kernal is that doesnt know how to debug `/usr/local/bin/python^M` ? Some, but a vanishingly small highly priorly knowledable group.

nyellin 5y ago
First of all, thank you for the comments. That said, I'm not claiming that you don't need any pre-requisites. Obviously this article is aimed at people who use bash or else they wouldn't be having an issue with the shebang! There is a huge audience who knows what a kernel is (in theory) and writes shell scripts, but doesn't know how shebangs work and has never actually looked at kernel code. My point isn't that you don't need prerequisites, rather that I think there is room for writing at a certain level while also giving people hooks to learn more. Anyway, I do appreciate the feedback. Thank you.

Beltalowda 5y ago

Let's say you have a book about a programming language; writing this in a way that anyone can follow – even those have never programmed before – would substantially increase the size of the book, as well as make it harder to follow for more experienced readers, since they will need to cut through all the stuff explaining the basics (loops, types, variables, etc.) in ways that a beginner can understand to get at the stuff they're actually interested in. Your approach works well for fairly short/simple concepts (although even in your article, there's a lot of assumed knowledge), but it gets harder the longer or more deep the content becomes. As for the posted article, I never had this problem. I suspect the author just bought badly written books; there are many of those, unfortunately.

k__ 5y ago

So, you say you write for "everyone who has a minimal relevant background" can read this. What does this even mean it the case of the article? The minimal relevant background is that you know how to copy a Python script with an \r to a Linux machine. This includes Python developers, for which this article is written. But it also includes non-Python developers. In fact, this even includes everyone who wants to run a Python script on a Linux machine. Administrators, but even regular users without much technical knowledge. So, our reader persona is the average Linux user. If I look at that article from the perspective of this persona, at least 80% of it doesn't help me at all. The article should start with the fix, and not redirect the reader to the end of the article.

nyellin 5y ago
Good point. Thank you.