Writing Better How To Content

Episode Breakdown

• 09:21 Know Your Audience

  “Before you even begin writing know who you are writing for.”

  Generally speaking you will encounter two types of users the technical user and the non technical user. The tone of your material will be different depending on which of these is you target audience. You will be writing to the lowest common denominator in your target group.

  “The dicotomy of technical vs non-technical user is one way to look at it but there is a gradient there.”

  The techical user is easiest to write for if your material has highly involved content with a need for a strong base knowledge. Basically the lowest common denominator is higher. However these users tend to be less lenient on mistakes made in tutorials.

  How would you explain this How To for your grandmother to understand? That is the attitude of writing for a non-technical audience. Knowing the lowest common denominator is difficult. If writing for a group of Millenials they are in general more tech savvy than a group of Baby Boomers. Walk them through the process explaining each step and avoid talking down to them.

• 15:02 Choose Your Topic Carefully

  “There’s something to be said for doing something you can do right now so that you can actually start moving forward.”

  When beginning to write tutorials start with a simple topic you know well and build out. Make your recording and writing mistakes on a topic you know well. There is a learning curve in creating content so don’t add complexity to that curve by writing on a topic you don’t know very well. Isolate the variables that you can control (topic, tone, media platform) and control them.

  “Quick early victories makes the writing process easier.”

  Make sure that your chosen topic is relative to the current trends and informative. Ask yourself if it provides value to those using it. The value proposition may not have value in and of itself but may provide value in the way it is presented.

• 18:15 Create a Clear and Succinct Title

  “You want to convey your content in as few words as possible.”

  Your topic can be a make or break point for the tutorial as it is the first impression potential users have of your skill and knowledge.

  First and foremost state what is being taught. Convey the context of the tutorial in as few words as possible while avoiding industry jargon. If you must use jargon or acronyms explain then at the outset of your tutorial.

  Avoid the “Buzzfeed” titles that are designed to be click bait. Outlandish claims and extremes in your title will attract attention but not from the users you are trying to reach. Most importantly don’t promise something in your title that you do not deliver in your tutorial.

• 21:18 Start With a Solid Introduction

  “You did this in papers in middle school, it’s the same kind of structure and it’s easier to read.”

  The introduction should summarize the topic you cover in the tutorial. The best introductions ask a question that is then answered in the body of the tutorial.

  “I write the introduction after writing the content.”

  Transition from the introduction to the body with a statement such as “Here’s how to in a few steps”

• 23:26 List the Supplies or Supplementals

  “Recipes: what happens when you are deciding Ok I’m going to make this thing and you find out 1/3 of the way through you need something?”

  Before you begin the instructions list out the tools needed for the task so that your users don’t find our half way through they need something and don’t have it.

  “There’s a concept in French cooking that basically states you cut up all the stuff you need before you start cooking.”

  Put your users in a position to fall into the pit of success by giving them all of the tools upfront. Let them be prepared and do not assume they know or have the materials. Make it easy to skim and scan the document.

• 26:35 Use a Step by Step Format

  “They are going to scan through it, not read it line by line.”

  Write your tutorial in second person and divide it into parts so that users can return and easily find their place. Psychologically this makes the user part of the tutorial. If what you are teaching can be done in mulitple ways address this at the appropriate steps explaining why your tutorial does it this way and provide references to other methods.

• 28:58 Avoid the BWoT (Big Wall of Text)

  “What they did was export it as an image, which is a complete jerk move it’s code.”

  The big wall of text problem can turn potential users of your tutorial away just as fast as not knowing the topic well enough to write a tutorial. Add pictures, graphs, code samples, or drawings to break the text up into more digestable chunks. This also helps users if they have to leave and come back to your tutorial as they may not recall the step they were on but will more easily remember a visual cue.

• 32:32 Your Media Platform Affects Your Presentation

  The platform you choose for your tutorial will affect the way you write and present your content. When writing a blog post you can be longer but need to worry about the BWoT trap and break up the text by dividing your post with subheadings, examples, and screen shots.

  Videos are generally more time limitted but can benefit users to be able to actively walk through the steps. Make sure to include detailed show notes as it will take users longer to follow along than the video takes and they may need to see code samples or want to copy/paste to try what you are doing in the video.

  “Make sure and do text PDFs and not render it as an image because that makes you a terrible person.”

  Other media includes podcasts, books, and PDFs. Podcasts are similar to videos in that you need to include detailed show notes so users can follow along better. Books and PDFs provide a larger format than blogs for written material and while the BWoT trap exists it is not as much a problem.

• 41:21 Edit Your Content

  “You are your worst editor, especially you now.”

  Get yourself an outside editor or two. In the best case scenario you will have a content editor that knows the topic well and an editor that does not know the topic. The latter should be able to follow your instructions without prior knowledge of the topic.

  If there is no other option for editing take some time away from the project before self editing. This is a last resort and some tricks to help include reading one paragraph at a time in reverse order and changing the margins of the document so that the flow is disrupted when you are reading.