4 ms·

The absolute beginner technical guide may be the most difficult kind of writing there is. You have to know what's already in the head of the absolute beginner.

by aazaa 6y ago

The absolute beginner technical guide may be the most difficult kind of writing there is. You have to know what's already in the head of the absolute beginner. If it's garbage, you need to set that straight before anything else can happen. You also have to know what's not in the head of an absolute beginner. Then you need to fill the gaps with background material. Not too much or your audience will tune out. Not too little or you'll lose your audience in a puff of confusion. There needs to be just enough instant gratification to keep the reader with you. Many concepts you've mastered are tangled together in your head, and you'll realize this the minute you start trying to write about them. Before you started writing, you never noticed what a hairball of concepts you'd mastered, and if you don't expend some serious effort and energy unpacking it all, your absolute beginner guide will read more like a dissertation. You'll need to untangle each and every concept for the beginner audience. That means getting creative with how information is presented. With what information you reveal, and what information you simplify - but not too much. You should start thinking about ways to convey ideas graphically, which could excite you as much as it horrifies you. A good image can take as much effort as 2,000 edited words. You start off thinking that it will be easy. And then you realize you've vastly underestimated how much material there will be to get where you wanted to be. If you haven't given up in complete frustration at the size of the undertaking in front of you, scale back your vision for the guide and repeat. It may take a few iterations before you know what you're doing.

ryandrake 6y ago
Yea, if I were writing something with the bold title "Absolute Beginner's Guide To..." I'd want to test it on my 8-year old who only knows how to launch the web browser and Minecraft. If she can use it successfully to cobble together a working Hello World program, then it's indeed an absolute beginner's guide.
- wonder_er 6y ago
  Not only can she cobble it together - it has to be something that helps her feel a sense of pride, dignity, and understanding. Some guides get someone to "the end", but they don't scaffold an understanding of the underlying principles, and the student feels even more confused at the end than at the beginning. I always go to great lengths to show the mistakes that I make all the time, and to show how much of a given domain I don't know. For example, in a Make an OSS contribution walk-through I did, I mention over and over how myself or the senior dev I was pairing with didn't understand something. [0] Most of the job of a modern software developer seems to be surfing across an ocean of complexity, avoiding everything except the _one specific issue_ we're working on. To persons unfamiliar with the field, they might think that we actually understand everything to any degree of depth. They would be deeply mistaken. [0]: https://intermediateruby.com/matt-swanson-jekyll-bug-p2 https://intermediateruby.com/matt-swanson-jekyll-bug-p2
- flukus 6y ago
  "Absolute beginners" does not mean there is no pre-requisite knowledge necessary, just no pre-requesite knowledge of C. If I took an "absolute beginners guide to calculus" it would be assumed or directly stated that the reader is expected to have some basic numeracy and literacy for the book.
EricE 6y ago
Otherwise known as The Curse of Knowledge. The reason so much documentation is garbage.
wonder_er 6y ago
> You also have to know what's not in the head of an absolute beginner. Then you need to fill the gaps with background material. Not too much or your audience will tune out. Not too little or you'll lose your audience in a puff of confusion. There needs to be just enough instant gratification to keep the reader with you. Couldn't agree more. I've spent probably a year incrementally revising a "getting started with Ruby" resource for a local software development program. [0] I ended up with a 45 minute (!!!) walk-through of how to run a test file of string manipulation exercises. [1] I treasure each of the ~500 views it's got. I spent probably 25 hours making, editing, and writing about that video. I think this video is the single most impactful thing I've ever made, in the last 10 years I've spent making things. I treasure the DMs I've gotten in Slack, from students who have found the video extremely helpful, encouraging, etc. [0]: https://github.com/turingschool/ruby-exercises https://github.com/turingschool/ruby-exercises [1]: https://www.youtube.com/watch?v=aeAkLxr5diE&feature=youtu.be https://www.youtube.com/watch?v=aeAkLxr5diE&feature=youtu.be

by aazaa 6y ago

ryandrake 6y ago

Yea, if I were writing something with the bold title "Absolute Beginner's Guide To..." I'd want to test it on my 8-year old who only knows how to launch the web browser and Minecraft. If she can use it successfully to cobble together a working Hello World program, then it's indeed an absolute beginner's guide.

wonder_er 6y ago
Not only can she cobble it together - it has to be something that helps her feel a sense of pride, dignity, and understanding. Some guides get someone to "the end", but they don't scaffold an understanding of the underlying principles, and the student feels even more confused at the end than at the beginning. I always go to great lengths to show the mistakes that I make all the time, and to show how much of a given domain I don't know. For example, in a Make an OSS contribution walk-through I did, I mention over and over how myself or the senior dev I was pairing with didn't understand something. [0] Most of the job of a modern software developer seems to be surfing across an ocean of complexity, avoiding everything except the _one specific issue_ we're working on. To persons unfamiliar with the field, they might think that we actually understand everything to any degree of depth. They would be deeply mistaken. [0]: https://intermediateruby.com/matt-swanson-jekyll-bug-p2 https://intermediateruby.com/matt-swanson-jekyll-bug-p2
flukus 6y ago
"Absolute beginners" does not mean there is no pre-requisite knowledge necessary, just no pre-requesite knowledge of C. If I took an "absolute beginners guide to calculus" it would be assumed or directly stated that the reader is expected to have some basic numeracy and literacy for the book.

EricE 6y ago

Otherwise known as The Curse of Knowledge. The reason so much documentation is garbage.

wonder_er 6y ago

> You also have to know what's not in the head of an absolute beginner. Then you need to fill the gaps with background material. Not too much or your audience will tune out. Not too little or you'll lose your audience in a puff of confusion. There needs to be just enough instant gratification to keep the reader with you. Couldn't agree more. I've spent probably a year incrementally revising a "getting started with Ruby" resource for a local software development program. [0] I ended up with a 45 minute (!!!) walk-through of how to run a test file of string manipulation exercises. [1] I treasure each of the ~500 views it's got. I spent probably 25 hours making, editing, and writing about that video. I think this video is the single most impactful thing I've ever made, in the last 10 years I've spent making things. I treasure the DMs I've gotten in Slack, from students who have found the video extremely helpful, encouraging, etc. [0]: https://github.com/turingschool/ruby-exercises https://github.com/turingschool/ruby-exercises [1]: https://www.youtube.com/watch?v=aeAkLxr5diE&feature=youtu.be https://www.youtube.com/watch?v=aeAkLxr5diE&feature=youtu.be