Joined: Fri Aug 30, 2002 1:09 am
Posts: 8543
Location: Southern California
|
BillG wrote: In today's world, many people cannot be made to read a manual. It's a chicken-and-egg situation. I haven't seen a decent manual written in the last few decades. Since they're all so poor, people have been conditioned to think manuals aren't worth reading. Since people don't read them, companies don't want to go to the expense of writing a good one...and the situation spirals on itself.
Chad and I had the following conversation offline, and he gave me permission to post it here.Quote: sburrow wrote: I want to ask you: How do you write your "lessons" so well? Your website in particular, all of the Primer pages, everything you write is compact but easy to read, is instructional but to all levels, is fun to read but still informative, is pure gold.
How do you do it? What strategies could I use to do something similar? Do you have a mental checklist or guide that you follow? Procedures to making a good tutorial? It's a very subjective matter, which is partly what makes it so difficult. I'll see what I can do here.
I write down things as I think of them, terribly out of order, and then edit. If something comes to mind but I don't take a jiffy to write it down because I'm not at that part yet, later I'll be thinking, "Now what was it I was supposed to say about this? I can't remember!" So I often stop in the middle of a phrase and write a couple of words below it to remind me to get back to something I need to address. It's like the thought buzzes the tower and then it's gone in a second, so I have to write it down immediately. If I think "Let me finish this sentence first," well, guess what happens.
This kind of thing would be very difficult to do in the days before we all had computers; but I did hear decades ago that when [a prolific write we both knew] wrote books, he'd write stuff out, and use scissors to cut it up and organize it on the floor, and tape things together in the desired order, get another thought and cut a section to insert it in between, etc.. It's so much easier now.
Then, keep in mind that everyone has so much material to read today that they'll quickly move on if you waste words on things that aren't important. That applies to the big stuff and the small alike. Regarding the big stuff, I told someone years ago that his material would be more inviting if it didn't start like a book with the title page, the copyright page, the dedication page, the acknowledgements page, the foreword, the disclaimer of warranty, the preface, the table of contents, before getting to the introduction. You'll lose the reader before you get to first base. (I haven't looked recently to see if he remedied that.) Get to the meat. At the opposite end of the scale, the smaller stuff might include individual words that aren't necessary, like "I broke my [right] arm" if it's not important to the reader which arm it was. Other times I find that I've gone to some detail about something that seemed important to me but won't be to the reader, so I delete it, in spite of all the time I spent on it, so the reader doesn't inadvertently also skip the more-relevant stuff.
Any place that things might be easier to read and digest as a bulleted or numbered list, go ahead and use one.
On anything that's not super urgent, I like to "let it ripen," ie, set it aside and come back to it hours or even days later and see if a fresh pair of eyes finds what I intended. Often this will alert me to a part that could be misunderstood, or that something assumes a background I forgot to lay, or some other little thing that needs fixing. It might also expose where I got tunnel-visioned.
At http://wilsonminesco.com/6502primer/PgmWrite.html, I used bold face to make phrases stand out, which might help navigate a page better where taking the space for big headings might make it too choppy.
After all of that, I sometimes still find, even years later, that something needs improvement, which is one of the reasons the 6502 primer (and other features on the site) frequently get edited. Things I read on the forum alert me to the need. I could say "He just needs to read it more carefully!"—which may be true, but there's probably also room for improvement in the way I said it.
I've practiced these things in stuff I write for work, too. It takes time, but it may waste more time later if I don't take the time now. For example, poorly written user manuals or installation manuals will result in more needed phone support and frustrated customers. When I was regularly writing manuals, I tried to pattern them off the manuals HP included with their calculators and hand-held computers of around 1980-85. You'd get a new calculator or computer, read through the manual from front to back, and at the end, feel like you know the machine pretty well, without ever having gotten to "the hard part"—because there was no hard part.Quote: I ask this because Rebecca [Chad's wife] has tasked me with making a user manual for the Acolyte computer and my latest video card. Here is what I have on the Acolyte so far:
[gave link, but it's no longer there]
I do not like it. Something about it just does not seem... right. I can't put my finger on it.
Also, I really do not like doing these things. I hate commenting my code so making a full document about commentary is probably even worse for me. I just don't have the motivation like I usually have when I'm creating something new.  Quote: In the debugging page of the primer, I wrote, "I sometimes catch bugs when further commenting code that's already working but not exhaustively tested yet. I comment as if trying to explain it to someone else who hasn't been following my train of thought on it. (If I come back to change it a year later, I'll need the comments anyway.) As a result of this madness, no user has ever found a software bug in any product or automated test equipment I programmed."Quote: Rebecca has often said, "You are teacher, so just write it like you are teaching!" But that doesn't help at all, I don't know why. It might be partly that students in a classroom have to listen to what you say, in the order you say it, without the option to skip around, see what's coming, etc., options which they will definitely exercise when reading. Also, when reading, they can't interrupt you to ask for clarification on something.Quote: Any suggestions? Tips and tricks and helpful hits? Is there some prototype or guidelines that I should follow? Any comments would be very helpful. The reader's unsettling feeling of unfamiliarity will be a continual enemy. Get ahead of it. Cut it off at the pass. Defeat it. You may lose the reader if the writing fails to give a feeling of a definite direction.
In grade school, we were taught to start a new paragraph about every four sentences. I have no idea where that came from. True, on the one hand, writing a whole page as a single paragraph repels the reader, and OTOH, I've gotten a lot of junk mail where each paragraph was a single short sentence, or not even a valid sentence, making it too choppy, and making me want to toss it. I try to keep reasonable lengths, starting a new paragraph where the thought changes somewhat, not just because the current paragraph reaches a certain length.
Even reading is taught incorrectly in grade school, IMO. You have to read something, and, "Pay attention, because you'll have to answer questions on it later!" In real life however, we usually start with the questions and then scan something to see if there might be anything relevant to the questions, something to slow down for, and if there doesn't seem to be, we move on. One of the first things I do every morning is to scan the forums. On the forums I don't have any responsibility on, I'll click on the sections that say they have new posts, scan the titles, and maybe click "Back" and then think, "I went so quickly I don't even remember what's there;" but then as if speaking to the writers, I say "You're going to have to get my attention faster than that." _________________ http://WilsonMinesCo.com/ lots of 6502 resources
The "second front page" is http://wilsonminesco.com/links.html .
What's an additional VIA among friends, anyhow?
|
|
Login
Register
FAQ
Search
well, OK, I guess that last one should really be hims! 
