| A good article with lots of thoughtful insights in how to write a programming book. The advice about assumptions we make about the reader's knowledge applies to much (most?) developer documentation too. The developer assumes the reader is an 'expert' at the same level as the developer. But too often the documentation provided is poorly written or incomplete. (Worst of all is when it simply doesn't exist.) My suggestions for programming tutorials - whether they be in written form or video: -- 1. Use graphics to illustrate programming constructs Graphics are ideal for explaining programming language constructs rather than wordy text-only explanations. Visual explanations remain surprisingly rare. I realise many developers don't feel confident sketching, but illustrating a programming construct can easily be done with simple shapes or readily available graphics. It's the visual explanation of the programming construct that matters, not how aesthetically pleasing is the sketch or diagram. Drawing with a wobbly hand on paper or a whiteboard can be a completely effective method to explain a topic. In fact, likely more effective than just text-only. -- 2. Seek inspiration from sources you would not consider (or consider beneath you) like tutorials for children These Usborne 1980s computing and coding books for kids have been shared before on Hacker News. These are really well-written guides. They are more readable and enjoyable to read than many programming books published for adults today. Take a look and consider how clearly they are written. Usborne 1980s Computer Books: https://usborne.com/gb/books/computer-and-coding-books Or consider another source: BBC Bitesize - a educational resource for UK school kids. Look at this example of explaining programming constructs. So much more enjoyable than reading a wordy, dense textbook written for grown-ups (see the animated video): https://www.bbc.co.uk/bitesize/guides/zh66pbk/revision/2 -- 3. Use realistic examples, or examples the reader can relate to This mirrors the advice in the article about using concrete examples. This is hard when using small examples to explain one idea at a time. However, using examples that the reader can relate to in real-life situations makes a difference to understanding. Also, consider your audience as international. You may think calculating baseball scores is fun, but if half (or more) of your readers or viewers have no clue about baseball, you'll lose their attention or comprehension. -- 4. Choose your metaphors carefully So many tutorials on Object-Oriented Programming (OOP) start with: "objects in programming languages are like objects in real life". Is it time to rethink this cliched (and often misleading) metaphor? -- 5. Finally, don't do this if you are making video tutorials on programming... This is a parody video, but I'm sure everyone has encountered video tutorials like this. Why are so many programming tutorials still like this? Every programming tutorial: https://www.youtube.com/watch?v=MAlSjtxy5ak |