I’m working on a side project that involves explaining software to newcomers. Stepping back from the project a bit, I seem to recognize a kind of design principle. It’s the curse of recursion.
When you’re explaining software, have it get out of its own way. Don’t use examples of the software in the examples showing how to use the software.
What this means is that in procedural, how-to-do-it training, you want your examples to show the software/tool/concept at work, and it’s rare that people use the software/tool/concept on itself.
If you were teaching basic HTML, your examples of code shouldn’t be about HTML tags. In other words, shouldn’t be like this:
<body>
<p>The <body>tag marks the beginning of what someone will see when they look at your page in a browser. The end of what they'll see is marked with the </body> tag.</p>
<p>The <p>tag marks each individual paragraph. As you write your code, it doesn't matter if you leave blank lines between words -- everything between a <p>tag and the next </p>tag will be considered part of the same paragraph.</p>
</body>
As I see it, your example is really a MacGuffin. When the content of the example looks like too much like the tool you’re talking about, you risk confusing your reader/learner.
A tutorial about using feed readers included a screen shot of one. Nearly all the blog posts in the screen shot were about blogging — a poor example for someone who hasn’t used a reader, because that person isn’t likely to care as much about the process of blogging as about an easy way to collect content (whether from blogs or other subscribeable pages.
The Head First books (see earlier post) nimbly avoid the curse of recursion. The Head First Guide to XHTML explains how to work with the code while having you build web pages for coffee shops, travel blogs, and lounges.
Hitchcock would approve.
Interesting stuff! I work with your other half, and she shared your info about setting up WordPress.