Looking back, it’s easy to be cynical about these titles. Each book contained a whole selection of games. You’d get a few pages of code (a lot to type on a ZX Spectrum keyboard at the age of 9), virtually no explanation, and a lavish watercolor picture supposed to illustrate the game play. When you’d got the whole game typed in, you’d run it and discover that the game consisted of a few lines of plain text. Most of them didn’t even use color. One game I remember was called “Archery”. I was excited to type it in — the watercolor was really stunning for that one. The game play looked like this: … .0… … . The “player” had to quickly hit the number corresponding to the position of the 0 (which was supposed to be an archers head poking out between the turrets of castle). It was thrilling. Being able to write a game myself, I knew I was on the bottom rung of a very long ladder that lead all the way to Jet Set Willy. 
I feel rather nostalgic that tools like Unreal Developer Kit and Unity3d are now free, and available to any 9 year old who wants to download them. Explore and playing around with the tools and techniques that bring you the games you love to play is a great experience… and I’m happy that a new generation of kids (as well as the rest of us) are going to get that chance.
RRW isn’t happy, uses words like “spam” here: http://www.readwriteweb.com/archives/amazon_turns_twitter_into_a_marketplace.php — seems a bit much when most people just get a bit of pocket money out of Affiliates.
Tools used: 3ds Max 2009Kathy taught me that if you can’t explain your mission in the form, “We help $TYPE_OF_PERSON be awesome at $THING,” you are not going to have passionate users. What’s your tagline? Can you fit it into that template?
This is the perfect single-sentence pitch for any book or educational product. It captures the target audience and the goal of the book in a few short, compelling words.
The trick is to define each of those variables in the most specific, vivid way that you can — and then let that mission drive everything about the book’s content and approach.
Not just “we help developers be awesome at Ext JS”, but…
“We help experienced web developers be awesome at building beautiful, interactive, and fun user interfaces using Ext JS”.
You can weigh every bit of content against a sentence like that, and you’ll know exactly what to leave in and what to leave out.
More from Geoffrey Pullum’s Language Log. Well known grammar and writing rules books often written by people with no clue about the rules of grammar.
The same could never be said of my blog… http://languagelog.ldc.upenn.edu/nll/?p=1854#more-1854Looking for a job? How about one where you set your own hours, you don’t have a boss, you have nothing to do but write at your own pace, you end up receiving fat royalty checks, and you don’t have to know anything at all about the topic that you write about? The job is to write non-fiction (textbooks and handbooks), only it’s OK if you don’t have a clue about the subject matter.
One word about your new career (and it’s not “Plastics”): grammar! The field where nobody much cares about anything that’s been discovered since the 18th century, and you don’t even need to get the 18th-century stuff right!
Over at Language Log, Geoffrey Pullum moans about user manual diagrams with meaningless labels. Watch out for nerdview — look at everything from your readers’ eyes.
Sarah Maddox writes about her experience on the “Here Be Dragons” project. Integrating Atlassian’s suite of collaboration apps is notoriously difficult. Sarah’s used technical writing to turn that into an asset. Instead of dry instructions she’s created a quest, and even built in a competitive element — readers tweet their status as they complete each stage of their quest.• Set software actions in the present tense. We want Missing Manuals to read asAnd a favorite peeve of mine (and every tech book editor, perhaps)…
if you’re standing over the reader’s shoulder, guiding her through a series of
steps. Software actions thus happen as you go. So instead of “The icon will
blink,” try “The icon blinks.” Save future tense for things that will happen later.
• Write as precisely as possible. Avoid sentences that start “There are” as in,
“There are four separate areas that make up….” Instead, try something like
“Four separate areas make up a Keynote screen.” Or “Keynote has four separate
areas that make up its screen.” You get the idea.
• Show clear cause and effect. When you want to explain how a program will
respond to an action on the reader’s part, avoid: “Click OK and Word reformats
the document.” Instead go for: “If you click the OK, then Word reformats the
document.” Or “When you click OK, Word reformats the document.” Also,
when you have a list of actions within a sentence, use “and then” to introduce
your final step. If you have just “and,” readers might wonder whether they
should be performing two actions simultaneously. But if you have just “then,”
you’ve committed a grammo because series of actions needs a conjunction to
link the last one to the rest of the sentence, and “then” is not a conjunction.
• Show readers the right order of events. When explaining how to do
something, tell readers where they should be before telling them what they
should do. For example: “In the Open dialog box, select the file….” (Not, “Select
the file in the Open dialog box.”)
So, Missing Manual Rule Number One: Your job is to act as the reader’s guide as you
take her through a tour of how the software works. In other words, keep the following
point in mind with every feature you describe:
What’s it for?
Nothing makes a reader want to hurl a book across the room more than a passage like
this: “In the Implement Freen Modules dialog box, you have options that let you
implement Freen modules in various ways.”
With each feature, you should never just say how it works. You should always, always,O’Reilly Missing Manuals are some of the best selling tech books out there. Of O’Reilly’s Top 25 sellers last week, 14 were Missing Manuals — that’s close to two thirds. Anybody who wants to write books that people want to buy should check them out. There’s nothing secret or unique about the Missing Manuals formula. Most of the advice in the document is best practice for accessible, interesting technical writing. What O’Reilly and Pogue Press has achieved is to reliably deliver books that meet these guidelines — and that’s the real challenge for publishers, editors, and authors.
always help readers understand why they would want to use a feature. A sentence like
“Open the Preferences window if you want to adjust your system preferences” is not only
dull, it also fails to advise the reader that, for example, he can make his monitor easier to
read by changing its preferences. Here are some examples of how to integrate this advice
smoothly into your sentences:
• “You’d find this useful in case of, for example, a power outage.”
• “There’s pretty much only one instance when you’d want this option turned off,
and that’s when…”
• “Although few people will use this setting, it’s designed to…”
• “Many PC fans don’t realize quite how powerful this checkbox can be.”
• “Microsoft’s engineers may have been overly optimistic in assessing the
importance of this feature.”
Here’s where you can really make a difference, setting yourself apart from the robot
authors who just catalog features. Readers love these assessments. Don’t just tell the
readers; advise them.
Over the years I have edited hundreds of books by authors of evey kind and stripe. Almost without fail, the best books come from the authors with the most irons in the fire . You know the type. These authors lead Fortune 500 companies, they teach executive education in top B-schools, they blog, consult, put on seminars, conduct large scale research studies and more. These are the owners of the laptops which produce the best books.
… so don’t come snivelling to me claiming that you are too busy to write.
Other reasons busy authors write the best books:
- They have something to say — lots of practical experience with their topic, and with the sort of people who want to read about it
- They know how to get things done quickly — lots of practice managing lots of commitments.
- The book isn’t their baby, it’s just a book — having a clear goal for the book is great. Being a perfectionist is not. Busy people don’t view the book as their life’s work.
- Busy people are focused outwards. They are writing because they want to reach PEOPLE, not because they want to create the perfect artefact or testimony to their talents. Busy people write useful books.
I’m changing MY focus. Packt as a publisher remains absolutely committed to Open Source. We’ve got plenty of new Open Source titles on the way, we’re running our usual Open Source CMS award, and have more Open Source titles than ever planned in the next 12 months. But for the time being, I am exploring other areas and invite book ideas and authors interested in writing on non Open Source topics.
I’m changing my focus at Packt to concentrate on commercial software. Over the past 5 years I’ve focused mainly on the hippy trippy world of Open Source: Moodle, Drupal, Joomla!, and so on. Now I’m shifting direction into commercial software tools. If you are an aspiring or would-be author who wants to write about tools and applications from Microsoft, Adobe, Autodesk, Apple, and so on then I want to talk to you. I’m especially keen to look at tools for developers, designers, web programmers, and other IT professionals. .NET, Azure, Live Services, iPhone Programming, Flash, Sketchup, 3ds Max, and so on are all on my list. As with our Open Source books, we’re interested in focused titles aimed at serious IT users. We won’t be publishing anything to rival the OS X Missing Manual or Excel for Dummies. But I’ll welcome ideas on novel, niche professional tasks using these tools. If you have skills in these areas and want to write, please get in touch. I’ll work with you to understand the skills you have, and develop a book idea that we both agree suits your skills, preferences, and the demands of the market. You can drop me a line by email on davidb@packtpub.com, or punch your details into my author profile form.
If you’re writing a tutorial, there’s a temptation to drag the reader around the tool and show them what everything does. That’s just advancing the reader over the scenery — they’re moving around, but they’re not doing anything else. From as early as possible, put some real action into your tutorial — give the reader challenges to overcome, cliff hangers, victories and solutions as they progress through those early chapters.Verbs tell us what is happening. The purpose of an adverb is to tell us how something is happening.
If you have a sentence like:
The cat sat on the mat.
… “sat” is the verb — it tells us what is happening. You can throw in an adverb:
The cat sat indulgently on the mat.
In general, skilled writers don’t use adverbs much. Unskilled writers use them a lot. And skilled writers delete most of the adverbs that creep into their first draft.
Adverbs are tricky. They seem to add detail, but usually they make your writing fuzzy. “The cat sat on the mat” conjures up a clear image in the reader’s mind. Everybody knows what a sitting cat looks like. Everybody knows what a mat looks like. You’re done.
But “indulgently”? How are we supposed to picture that? It’s complicated. A simple, vivid image becomes too complex to process.
You can avoid adverbs most of the time by cutting them out — the reader can do just fine without the extra information.
Contents
[hide]
From the Flash Lite Quick Start. I’d probably skip the “Technical Overview” and go straight to the “Getting Started” part. What about you?
And if most people are like me, why isn’t the Technical Overview tucked away in the appendix?
