I wrote a web programming book three years ago (moderately successful, made back its advance, and got me the career change I was looking for) using a philosophy that has a very similar approach to this. My approach is:
1. All code examples must lead to a working program, or can be easily integrated into a working program. Preferably the program has trivial functionality. Conceptual material must relate back to a working example.
2. Avoid applying excessive cognitive load to the readers. Human short term memory has a capacity of 7±2 items. Your material must be pitched at a level where there is a maximum of five concepts in play at any one time (five being the maximum "guaranteed" short term memory for a healthy adult). This is much easier to acheive with goal 1 as it the approach guides the writer as to which item needs to be explained next.
From that perspective, unix man pages drive me nuts. Learning to read man pages is one of the core skills that needs to be developed in order to become an effective user of unix like systems.
the idea of 'five concepts' is interesting as it's related to the level you're pitching at. The idea is that you get people up and running with the initial working code, and if they manage that, then they can follow what you're doing subsequently, and you can keep a feel of their levels of consolidated knowledge.
1. All code examples must lead to a working program, or can be easily integrated into a working program. Preferably the program has trivial functionality. Conceptual material must relate back to a working example.
2. Avoid applying excessive cognitive load to the readers. Human short term memory has a capacity of 7±2 items. Your material must be pitched at a level where there is a maximum of five concepts in play at any one time (five being the maximum "guaranteed" short term memory for a healthy adult). This is much easier to acheive with goal 1 as it the approach guides the writer as to which item needs to be explained next.
From that perspective, unix man pages drive me nuts. Learning to read man pages is one of the core skills that needs to be developed in order to become an effective user of unix like systems.