Tips for writing helpful "how to" content

Prompt ai is like hiring a bot as the latest member of your team. He/she/it acts as your first line of interaction with customers, fulfilling requests for info and allowing folks to make tickets.

Like any bot, Prompt ai is as smart as the info you feed it. 

Now on to the 5 tips...

Tip 1: Write for scanners

Write for people who scan. That means pretty much everyone who interacts with Prompt ai. Nobody reads. 

  • Use numbered lists for sequential steps
  • Use bullets for lists of choices or options
  • Use white space (lists help here)
  • Use consistent formatting – Most importantly, use bold to highlight actionable items (stuff to click)

Bonus tip: Start your Solution with a phrase like "Here's how to...." Keep in mind that your users won't see the title of the Solution, so it's useful to repeat it for them. 

Tip 2: Be consistent.

Use the same word for the same action. Each and every time.

Use the same formatting (bold) for everything the user has to click or complete.

This isn't creative writing class. You don't get bonus points for stylistic flair. 

 

Tip 3. Location, location, location

Make sure the reader knows where they are.  

Use a [step] and [step result] structure like this:

  1. At the top of the page, click Settings. [step]
    The Account Settings page is displayed. [step result]

This may seem extreme, but it works. And to save words in your [stepresult], avoid the future tense.

Bonus tip: Put the location first. Compare these two items that say the same thing. While the second is more natural when spoken, in writing it can lead to a problem. Your brain stops at "Click Change" and goes to the UI to look for the button. On a well-designed interface, that may not be a problem. But for a longer procedure covering a noisy interface, you might lose folks. By putting the location first, you force the reader to hang in there for the actionable part (the bold item).

  • Next to your password, click Change.
  • Click Change next to your password. 

Tip 4. Beware the screenshot!

Don't use too many screenshots in your bot content. They can burn you.

For starters, they're just too big. Remember that folks want to scan. Some know more than others. Some folks want to jump quickly to the part they don't know. If you gum up the message box with screenshots, you are forcing the reader to process far more information. They have to scroll more. They have to check the shot, understand if it is relevant, understand which parts of it are valid. Screenshots... brrrr.

Bottom line on screenshots:

  • Use screenshots when the interface is truly confusing – like when referring to an obscure icon without a tooltip on a busy interface that looks like either a star or maybe an octopus or is it a... you get the idea 
  • If you do use shots, always provide instructions in words, as well. 
  • Make sure that each screenshot has numbering that corresponds to the documented steps.
  • Do not add a screenshot for every step
  • Do not add a screenshot for UI elements that are totally obvious and easy to name
  • You end up with cleaner material that's scannable without extra noise from screenshots.

Tip 5: When in doubt, follow a style guide

If you're reading this, writing is probably not your main job. No worries. Lots of other folks who are writers have been there, done that. And since they like writing, they've written a lot about what they've learned: Style Guides.

When should you turn to a style guide? Pretty much every time you aren't sure about word choice, grammar, formatting, or even layout. 

Do you need your own style guide? I say no. Start with the Microsoft Style Guide. Share it with your team. Bookmark it. Refer to it when confused or in a dispute. It will be your friend.