how to write "how to's" documents

4

Click here to load reader

Upload: jose-valerio

Post on 12-Mar-2016

229 views

Category:

Documents


3 download

DESCRIPTION

User Guide

TRANSCRIPT

Page 1: How to write "How To's" documents

Document Revision: V1.02 José Valerio Document Revision: V1.02 José Valerio Document Revision: V1.02 José Valerio Document Revision: V1.02 José Valerio page 1

Writing How-To’s Guide By: José Valerio (AOSUG Member)

http://jose-valerio.com.ar/blog September, 2009

IntroductionIntroductionIntroductionIntroduction

Page 2: How to write "How To's" documents

Document Revision: V1.02 José Valerio Document Revision: V1.02 José Valerio Document Revision: V1.02 José Valerio Document Revision: V1.02 José Valerio page 2

The main purpose for this document is to provide a clear guide about how to create a good document in the group. It’s very important to transmit the knowledge correctly to others who will follow up the instructions trying to reproduce what you did. Please note that writing a “How To” document it’s really different to write a “White Paper”. How-to writing is a genre that appeals to most students because it is applicable in the world. This genre involves exploring interests and needs to identify a topic, conducting several research methods, and working through the writing process. We see many How-To’s every day. Some are written by professional writers, but most are written by people just like you. Tutorials are a way of passing on your knowledge and giving something back to the community. The tips below will help you to create instructional articles that are easy to read and understand. HaveHaveHaveHave in mind the “How To” main purposein mind the “How To” main purposein mind the “How To” main purposein mind the “How To” main purpose Example: “Installing Oracle 10g R2 on OpenSolaris 0609” Make it scannable.Make it scannable.Make it scannable.Make it scannable. Create an outline before you start. Type the main points as you think of them. When you're done, organize them into steps. use bullets, numbers or headings to make them stand out, then fill in the details. Readers should be able to get an overview of your tutorial at a glance. Use proper grammar and punctuation.Use proper grammar and punctuation.Use proper grammar and punctuation.Use proper grammar and punctuation. You don't have to be an English professor. Just use complete sentences, capitalize only when necessary, don't mix up your periods and commas, and so on. Your goal is to make your how-to as easy to read as possible. Begin with an introductory paragraph.Begin with an introductory paragraph.Begin with an introductory paragraph.Begin with an introductory paragraph. Introduce your how-to by telling your readers what they'll be learning. If there's room, you can also tell them why you've written the article and what your qualifications are. Don't try to squeeze in too much information. The focus should be on the knowledge you're providing. Remember your humble beginnings.Remember your humble beginnings.Remember your humble beginnings.Remember your humble beginnings. Think back to when you first began learning about your topic. Things that seem obvious now were a mystery then. If you could go back in time, what would you tell yourself to make things easier? This is the same advice that will pave a smooth path for your students. Tell them how, not about.Tell them how, not about.Tell them how, not about.Tell them how, not about. Many of the tutorials we see are written without real instructions. For example, rather than saying, "Trace a circle.", they might say, "When doing this sort of thing, I like to trace a circle." Don't confuse your readers. Clearly define the steps that they need to take. Keep your paragraphs biteKeep your paragraphs biteKeep your paragraphs biteKeep your paragraphs bite----sized.sized.sized.sized. Research has shown that the average reader learns best when paragraphs are 3-5 sentences long. This helps them to digest each idea before they move on to the next one. It also helps you maintain enough white space. Use white space.Use white space.Use white space.Use white space.

Page 3: How to write "How To's" documents

Document Revision: V1.02 José Valerio Document Revision: V1.02 José Valerio Document Revision: V1.02 José Valerio Document Revision: V1.02 José Valerio page 3

The use of whitespace increases readability. Leave a couple of blank lines between sections. Look at the finished article as a whole and ask yourself, "Does it look too crowded?". Especially when a topic is difficult, a big mass of words can distract your reader from learning. Remove unnecessary words.Remove unnecessary words.Remove unnecessary words.Remove unnecessary words. EXAMPLE: "Some people don't like hand drills (I do), but to get this part right, you really need to use a hand drill." THE EDIT: "You'll need a hand drill for this next step." Try for variety.Try for variety.Try for variety.Try for variety. Your how-to may be about cats, but there are only so many times you can use the word "cat" before you bore your readers. First, ask yourself if a word really needs to be in the sentence. Second, consider similes; for example, "kitty", "feline", "furry friend" and so on. Use simple language.Use simple language.Use simple language.Use simple language. The average adult reads at an eighth grade level. To reach your audience, write in the clearest, simplest manner possible. For example, the word "copy" is better than the word "replicate". Avoid lingo.Avoid lingo.Avoid lingo.Avoid lingo. Experts tend to create their own languages. Most readers, however, will tune out if a word they don't know shows up without explanation. Don't use lingo unless it's necessary. Be sure to provide simple definitions. Let your readers get used to a new word before you introduce another one. Use acronyms sparingly.Use acronyms sparingly.Use acronyms sparingly.Use acronyms sparingly. Acronyms can be useful, but overusing them will cost you readers. No-one wants to wade through a sentence like this: "Your SDRAM/DDRAM will depend on your MB, CPu and OS." Some things are better spelled out: "The type of memory you'll need (SDRAM or DDRAM) will depend on the requirements of your motherboard, CPu and operating system." Stay Stay Stay Stay positive.positive.positive.positive. Replace negatives with positives wherever possible. Some examples: "Don't smudge your work." is replaced with "Rest your hand on a piece of paper to avoid smudging." "Only the uncivilized gulp their wine." is replaced with "Sip your wine slowly to fully appreciate its flavor." Stories help learners.Stories help learners.Stories help learners.Stories help learners. People remember articles that are entertaining. A short story or joke that illustrates a point can enhance your tutorial. As always, balance is the key. Remember your instructional goal and stick to the topic at hand. Pictures are your friends.Pictures are your friends.Pictures are your friends.Pictures are your friends.

Page 4: How to write "How To's" documents

Document Revision: V1.02 José Valerio Document Revision: V1.02 José Valerio Document Revision: V1.02 José Valerio Document Revision: V1.02 José Valerio page 4

A picture really can be worth a thousand words. If you're trying to describe a dance step, for example, words won't work as well as a diagram or a photo. On the other hand, don't crowd the page with unnecessary graphics, especially animated ones. They'll distract your readers. Promote gently.Promote gently.Promote gently.Promote gently. Many businesses write tutorials to promote their product or service. Avoid overtly promotional articles. They turn readers off. Instead, focus on how-tos that compliment what you sell. For example, an auto repair shop might write a tutorial called 'How To Know When It's Time For A Tune-up'. An art supplies store might offer 'How To Paint using Acrylics'. There's no need to refer to your company in the article. After all, your business name and contact information should already be on every page. Wrap it up.Wrap it up.Wrap it up.Wrap it up. An article without a closing paragraph feels unfinished. Summarize what the reader has just learned. If you're willing to answer questions, say so. End on an upbeat note. Review and share your document before publish it.Review and share your document before publish it.Review and share your document before publish it.Review and share your document before publish it. It is always a good practice share your document with others members requesting feedback, this assures the document quality. Go back and edit.Go back and edit.Go back and edit.Go back and edit. Once your tutorial is complete, read it aloud. Does it flow easily or are you stumbling as you read? Note where the problems occur. Then go back and rewrite until everything flows smoothly. Finally, use your spell checker and correct any errors. We've come to the closing paragraph. In a nutshell, anyone can write a successful how-to. Keep these tips handy for reference, and you'll be well on your way. Your knowledge is valuable, and someone out there is waiting to learn from you!

Happy writing!

This document was a recompilation based on many open sources and articles about how to write “How To”s. Use it as a guide to

produce professional documents.