David Barnes @ Packt

Your tutorial needs an introduction. The point of the introduction is to tell the reader what they'll learn in the tutorial, get them juiced up about it, and help them to prepare their minds for what's ahead.

An introduction in a technical tutorial should not introduce anything technical. It is an introduction to the tutorial itself, not to the technology you are discussing.

The introduction to a tutorial should have the following parts:

1. Context: A sentence that reminds the reader where they are already, and perhaps why they need to learn more. For example: "In the last chapter we saw how to store information in the computer's memory using variables."
   
2. Outcome: What's the reader going to accomplish in the chapter? What will the chapter do for them? What's the theme? State it in one chapter, using the most jargon-free language you can: "In this chapter, you'll see how to use information in the computer's memory to make various decisions, and affect what your program does."
3. How we'll get there: Now break down the task into its main stages or sections. Usually you'll do this with a bullet list -- one for each major section or stage in the chapter. One of the bullets in this chapter might be: "Use different kinds of loops to get the computer doing the same thing over and over again until a certain condition is met, or the loops gone around enough times." You'll need to introduce this list with a sentence such as "We will do this by:" or "Specifically you will learn how to:"
   
4. Restate outcome: After the list, restate the outcome in a different way. Something like: "By the end of this chapter, you'll have no problem using these techniques to control the logic in your programs".
   
5. Restate context: The introduction starts by telling the reader where they are now, and why they need to learn more. Finish the introduction by telling them where they will be by the end... how will their world be better: "Once you've mastered this, you'll be able to write some entertaining interactive programs, and will be ready to move onto more advanced programming topics."
6. Finally, move onto the content: End the introduction with something that moves the reader into the main content of the chapter: "So without further ado, let's get started."

Loading mentions Retweet

A few weeks ago I conducted an experiment in speed writing. First I converted the basement of the Packt offices into a prison with 500 single person cells. I then invited 500 Joomla! power users to the Packt offices, telling them it was for an "open source for profit" conference and Packt would provide the pizza. They all came. Who could resist?

I split them into 2 groups. To each member of group one I gave the following task:

Write 1000 words explaining the virtues of the Joomla! CMS.

To group two, I asked something more complex:

1. Identify 3 specific reasons why you like Joomla! so much
2. Write 350 words explaining each reason and giving specific examples

In both groups, the subjects would be released from their cell upon editorial acceptance of the written material.

The results were pronounced. Group two all completed the task successfully in under an hour, and have been allowed to return to their families. I haven't heard from group one for a while. I hope that they are OK.

So a couple of hundred Joomla! geeks go missing. What's the big deal?

There's a lesson. It is much, much easier to write 350 words 3 times than it is to write 1000 words. It's much, much easier to write about something specific (one of things you like) than to write about a whole bunch of things ("the virtues" of Joomla!). And usually, 3 specific benefits will be a more compelling read than a generalized discussion of all the benefits.

This is why you can write a 350 word email or response to a blog post in what feels like a few minutes while writing a page of a book can take hours.

Try to write in 350 word chunks -- this is why you should have a chapter plan. 350 words is about as much as you can write "off the cuff" before you start worrying about restructuring, or you start to lose track of what's going on. It's why you should have plenty of headings planned before you start writing the body text -- it breaks up your task into manageable chunks. Try writing something now. I bet you start to run out of steam after about that long.

Identify the specifics before you start writing -- try not to write about a topic. Instead support a point, explain a concept, describe a task. Writing about a topic is a sure way to writers' block.

We won't be running any more prison experiments for a while. Even so, don't be imprisoned by your writing task. Break it down.

Loading mentions Retweet

When I write technical content, I aim for roughly one heading every 3 paragraphs of text. I use different levels of heading (H1, H2, H3) if the document is more than a few pages. And I use several different types of heading too.

Headings make it easier for people to jump around in your writing. If it's easier to jump around, it's more likely people will read. Especially blog posts. When I find a new post I don't read it from the top straight away. I scroll through to see its main points. If they look interesting I will explore in more detail.

The main way an author can hold my attention -- and most people's -- is with headings and images.

Here are the main heading types you can use in your writing, and how much I personally like each one.

Statement / Support -- summarize your point
This is where the heading acts as a headline, summarizing the point that follows. Daily Mail front pages follow this pattern... the headline summarizes the story, the rest of the article provides the details and supporting evidence.

Examples: Joomla is great for ecommerce!, Moodle: the perfect tool for cutting edge teachers.

Dave's rating: ****

Command / Instruction -- tell the reader what to do
The heading tells the reader to do something, the content tells them how or why.

Examples: Create a new blog post, Install WordPress, Process your orders.

Dave's rating: ****

(A variation on this is "promise/fulfillment". For example: Never gain weight again, Find a perfect partner for life. After headings like that, you expect the text to tell you how.)

Process / Instruction -- tell them what they will learn to do
This is similar to Command / Instruction, all you do is change the first word so that it ends in -ing.

Examples: Creating a new blog post, Installing WordPress, Processing your orders, Finding a perfect partner for life, Never gaining weight again.

Somehow, changing that word makes the heading a little less punchy, a little more polite. It cools down the statement, makes it less agressive. It also makes it feel less exciting or urgent. It sounds like a process to learn about, rather than an action to perform.

Dave's rating: *** (I prefer punchy)

Object / Description -- name the topic you're going to tell them about
At their worst, the heading is a piece of jargon or a technical term, and the description is a definition of that term. This is a recipe for immediate snoozing or confusion from the reader.

This is one of the most commonly used heading patterns -- it should be the rarest.

Examples: The Do Loop, Home page, Walls, printLn(), heading types

This heading style works well for reference material. Any document that uses this style too much will end up looking like a reference.

Dave's rating: *

(The first draft of this blog post used this style of heading -- and I was about to post it before I realized the enormity of my sin. These headings are a constant temptation for writers. Before sending off a chapter or publishing a blog post, see if you can replace them with a more compelling style.

In my case, I added a "statement" heading to the end of the Object/Description heading -- and now the article is much better.)

Question / Answer -- pose a question with your headings
The heading asks a question, the content answers it. Works well if the genuinely cares about the question and wants to know the answer. Ideally, it should be a question that the reader is already asking themselves. (And I mean really asking themselves, as in... "Wow! How do I do that?" not as in, "Yeah, but so what?")

Examples: So, how can I do that in my own programs?

I would only use this for "deep" headings -- level 3 and below.

Dave's rating: **

Container / Content -- tell the reader what's coming up
The way the heading is written makes it clear what sort of content comes next.

Examples: 10 Top Tips for Getting More Followers on Twitter, Advantages of Moodle, How to Create Compelling Content, Pictured: Harry's Brand New Girlfriend, Warning!

These headings do not make sense on their own. Instead, they signal the sort of content to follow. Most headings containing the word "these" will fall into this category, including the title of this article.

Dave's rating: ***

You can combine these patterns together to form even better headings. For example: "Do you make these mistakes in English?" -- it asks a question, and it's also a container. The question doesn't strictly make sense until you've read the answer.

Loading mentions Retweet

       

Click here to download:

Good_writing_should_be_like_Al.zip (127 KB)

Writing a computer or other "how to" book, you walk a tough line between too formal and too informal. It's not easy to stay balanced.

Try to write in a way that it friendly, approachable, and shows some personality -- without imposing yourself too much on the reader. Think of how traditional chat show hosts create a rapport with their subjects, while retaining a respectful distance and letting their guests focus on themselves (something for which their guests need little encouragement).

Don't use stiff and starchy language. Use contractions (we're, let's, I'm) when appropriate. Don't use too many stuffy words that normal people only see written down (ergonomic, leverage, functionality, pedagogical). Write in a way that sounds good when you read it out loud.

But don't use slang either. Spare words like "cool" and "rocks". You're not Ali G and there's nothing worse than a teacher who tries too hard to get down with the kids. It doesn't make them seem credible -- it means they lose the credibility and authority that they might naturally have.

Dress your writing in tie and tank top. It's a good look on you

Loading mentions Retweet

In Seth's blog post from last year, he talks about two components of any how to book:

• Recipes -- how to do it
• Persuasion -- why to do it

Most business books are mainly persuasion. The ideas in them are easy to summarize -- getting you to do something with them is the hard part. Most computer books are mainly recipes -- telling you exactly how to do stuff.

Even so, all computer books need to do some persuading. Before a cookbook presents a recipe, it has to convince you that it'll taste good: otherwise you won't bother to make it.

Books for beginners -- especially tutorials -- need more persuasion than books for professionals. Whatever your topic, find the sweet spot. How much time should you spend motivating the reader, getting them to try the next action, adopt the next best practice, or even just move to the next chapter?

Loading mentions Retweet

The Day You Became a Better Writer

I went from being a bad writer to a good writer after taking a one-day course in “business writing.” I couldn’t believe how simple it was. I’ll tell you the main tricks here so you don’t have to waste a day in class.

Writing Funny

Today I will teach you how to write funny. I will be referring to my earlier post about the world’s tallest man. Read that one first, two posts below, if you haven’t already.

Loading mentions Retweet

Right now I am looking for authors and book ideas to publish in late 2009. I plan to publish 8-10 books in Q4, and would like to hear from potential authors and people with book ideas. If you are interested, please contact me.

Here are some areas I'm especially interested in at the moment:

• Books that complement Packt's existing line up in Drupal, Moodle, WordPress, Joomla!, jQuery, Ext JS, CakePHP, etc. We've already published books in these area. What else might readers of these books want? If you know these tools and are keen to write, get in touch with me anyway. We can discuss specific book ideas.
• Open source web tools are where it's at: CMSs, blog platforms, JavaScript libraries, server side programming, and so on.
• Targetted, specialized titles on major topic areas: PHP, Rails, Python, ASP.NET. There are already plenty of general books on these topics -- what specific avenues are unexplored?
• Web 2.0 tools, guerilla marketing online, recession proof IT strategies and ideas.
• The sweet spot for Packt is 250-350 pages, with price ranges of $40-$60. This equates to 10-12 chapters of 25-30 pages each.
• Think about the knowledge, skills and experience you already have. Writing about things you have done, telling success stories, sharing experiences are all valuable in computer books. They don't all have to read like comprehensive technical manuals.
• Think niche: look for a narrow target audience, a specific need, and develop a book idea that will satisfy it.

If you're interested in writing, Packt pays a competitive royalty (15% of revenues on printed sales, 25% on ebooks). You don't need to write a full book proposal. Short pitches are more likely to get my attention: a quick summary of what the book is about, a description of the target audience, and some key selling points. It need not take more than a few minutes to capture the essence of your idea and send it to me. Email davidb@packtpub.com.

Loading mentions Retweet

I read an article over at Freelance Switch yesterday called "Dissecting the Logo Design Creation Process". It was one of the most useful articles I've read in a while (or would be if I was regularly called on to design logos).

A while later I realized that the article gave me no advice at all one what makes a good logo, design tips, or ideas for composition, fonts or colors. Instead the article focused entirely on process.

Capturing a process in writing means breaking a task down into a set of steps, and telling the reader what you do in each step.

Don't focus on how to do it well, just how to do it at all. Because this was an article about designing logos, for each step she showed a picture of what she had at the end of that step. So we know exactly what sort of output we can expect.

Most authors I work with don't see the value of writing out a process. Perhaps because once a process is familiar, it seems so obvious as to barely be worth sharing. Yet it is one of the main things I wish all authors of practical books would give me. When you come to teach the reader a new skill, don't try to capture the magical talent, hard earned experience, or special technical knowledge that leads to success. First of all, get the process out clearly. Break the task down into the main steps that you go through when you carry out the task, and simply describe what you do. Show an example as you go.

Try to capture in writing what the reader would see if they were watching you over your shoulder as you did the work yourself.

Once you get into the habit of capturing processes in writing, you'll discover writing can really be quite easy... and that it's suddenly much quicker to fill pages with high quality, relevant writing in a short time. Give it a try.

Here's that article: Dissecting the Logo Design Creation Process. Look at how it's written, and see what you can learn for your own writing.

Of course once that process is set up, the author could give us more information about how to do a good job at each stage... how to find the best imagery, how to come up with cool logo concepts, how to choose the best colours and fonts. She's given her article a strong skeleton, and can now attach as much flesh as she wants.

Loading mentions Retweet