Rules for Writing Software Tutorials \ stacker news ~Design

pull down to refresh

Rules for Writing Software Tutorials refactoringenglish.com/chapters/rules-for-software-tutorials/

62 sats \ 3 comments \ @nym 3 Jan Design

Most software tutorials are tragically flawed.

Tutorials often forget to mention some key detail, preventing readers from replicating the author’s process. Other times, the author brings in hidden assumptions that don’t match their readers’ expectations.

The good news is that it’s easier than you think to write an exceptional software tutorial. You can stand out in a sea of mediocre guides by following a few simple rules.

view all related items

6 sats \ 0 replies \ @runningbitcoin 3 Jan

Thanks for sharing!

4 sats \ 1 reply \ @Design_r 3 Jan

Now I don't believe that setting rules works, but this article is a great resource and it exemplifies how a writer could do a bit of UX research before filling up a white page. Thank you for posting this here, indeed, writing and architecting information is definitely a creative and design process. @nout from ~tutorials and @Darthcoin will may have something to say about it

0 sats \ 0 replies \ @DarthCoin 3 Jan

Writing Bitcoin guides for noobs is really hard. You will always end up in mentioning some technical terms that even for a normal bitcoiner are hard to grasp. I've seen many bitcoiners that have no idea what is a HTLC or what are the main LN implementations.

So for example making a guide about a LN wallet it is impossible not to talk about HTLC and LN implementations. Then the focus on wallet is distracted and you have to insert links and short explanations to other guides. But that's the thing, readers, especially noobs do not pay attention to those links (that are important) and they just move on reading, but not understanding too much.

In all my guides I tried to add as much information I can, to have it in one place so if the reader really want to learn the whole thing, can click on links and resources.

You can't just read a single guide and say, ok now I understand how this app works. No, you have to read more.

But yeah, I like to structure my guides in 3 main parts: introduction, tutorial, conclusion with added resources links. Sometimes is longer sometimes is shorter.