10 (More) Writing Guidelines for SaaS Applications

“The words you choose within your app are an essential part of its user experience.” Apple guidelines on writing for web applications

One of the challenges of developing a web application is that you can’t see how customers are using your application.

When I lived in Shanghai years back, I remember showing an ex-pat finance manager how to ‘double click’ and witnessing his struggle to click at just the right moment. I can still see the frustration on his face. Why doesn’t it work?

When writing instructions, you need to be more than specific – you must be super specific. And, you can’t assume they know what you know aka the curse of knowledge.

Why is this important?

Your product has to compete with an increasing number of rivals. When you do land a prospective customer, make sure that the instructions are easy to follow, relevant, and unambiguous. You probably know this but with many things, it’s good to get the occasional reminder.

This week, I started a new project providing F1, tooltips and other helper information for an ecommerce site. Before typing a word, I blocked out time to re-examine best practises for web writing, and catch up on new trends I should be aware.

While the writing recommendations haven’t changed, a few things caught my attention I’d like to share. Here are two from Apple and Microsoft’s guidelines for web writing. .

Apple – Write for how people use each device

People may use your app on several types of devices. While your language needs to be consistent across them, think about where it would be helpful to adjust your text to make it suitable for different devices.

Make sure you describe gestures correctly on each device — for example, not saying “click” for a touch device like iPhone or iPad where you mean “tap.”

Writing guidelines for web applications: Apple Writing Guidelines

Establish patterns in content

Microsoft’s guidelines explain how to write more ‘scannable’ content. While you probably ‘know’ this, the editors provide some additional context. The concept of ‘landmarks’ is something I’m going to examine and plan to weave into my content.

Apply these tactics throughout your content to create familiar landmarks for your readers:

• Lead with what’s most important. Place important keywords near the beginning of headings, table entries, and paragraphs so they’re easy to spot.
• Use text formatting consistently, such as using bold in procedures to identify UI labels. To learn more, see Text formatting.
• Apply the same sentence structures to similar information. For example, use prepositional phrases consistently in procedures to help customers navigate menus and dialog boxes. And use the same syntax for cross-references and other common content elements.

Read: Microsoft Technical Writing Guidelines 

10 Guidelines for Writing Documentation for SaaS applications

Focus on solving user problems by using consistent ‘easy-to-skim’ language and imagery that provides values to the user.

When writing documentation for SaaS applications, consider the following:

1. Registration – explain how to set up the account, register an account, common setup issues, and troubleshooting, for example, if they lose their password.
2. Settings – this includes the log in, log out, and account settings. What the user can do once they are authorized to use the application.
3. Navigation – explain to the reader how to get around the application. Are there any additional settings they can turn on? Can they customize the screen? If so, how and where?
4. Windows – identify the main windows and dialog boxes, and what you can achieve in each.
5. User Interface Controls – describe the location and purpose of buttons and icons on the user interface.
6. Configuration Settings – explain to the user how to change any setting on the application. For example, how to change the size, color, position, or values of the screens. Another option is to show them how to add new columns, fields, or customize it, for example, changing the background to a different colour.
7. Tasks – make a list of the main task. Gather related tasks under specific headings. This usually matches the user interface but there can be overlap with other screens. Prioritize the list and describe the most important tasks first.
8. Reference – this explains the purpose of every column, text field, drop-down menu, and every option in these menus. Most of these are self-explanatory but you need to account for fields whose purpose is unclear.
9. Known issues – identify any known issues with the application. For example, if more than five screens are opened at the same time, performance may be impacted.
10. Warnings – protect users from losing valuable data. Highlight actions that cannot be undone or could have catastrophic consequences.

In addition, consider the following when you start crafting the actual content:

• User Needs – Focus on solving the user’s problems or needs. Explain how your product can help them accomplish tasks more efficiently or effectively. Use language that resonates with their goals. Avoid talking over the reader. Write to their level.
• Think mobile – Keep sentences short, direct and ‘scannable’. As many users skim content, break up long paragraphs and use headers, bullet points and bold text to highlight key information.
• Clarity – Explain features and functionality clearly. Avoid jargon. Define any technical terms needed to help users understand how to use your product. Use examples if helpful.
• FAQs – Address common questions and objections. Anticipate what questions users may have and answer them proactively.
• Active Voice – Use active voice and avoid passive constructions. Active voice is more concise and engaging. For example, “The software generates data automatically” rather than “Data is generated automatically by the software.”
• Benefits – Focus on benefits, not just features. Explain how product features translate into user benefits. Link features to concrete use cases and outcomes.
• Terminology – Use consistent terminology and messaging aligned with your brand voice. Maintain consistency in language and tone across all content assets.
• Imagery – Include relevant images, graphics, videos or screenshots to illustrate your points. Visual content improves engagement and comprehension.
• SEO – Optimize content for SEO where possible by including relevant keywords. This helps users find your content online.
• Proofread – Review and edit carefully for organization, grammar and spelling before publishing. Error-free content builds credibility.

The Finer Points

By focusing on the user’s needs instead of selling the features, you build trust, drive adoption, and increase customer retention of your SaaS product.

Remember, your job as a writer isn’t to write content. Content is just a commodity. Rather, it’s to provide the right words, in the right order, to help another person do something – often when in a hurry, under stress, on a small phone…

And remember, as you’re not sitting next to them – as I was when showing my friend how to double click –your writing must be watertight. Do they have the exact information they need at this specific moment?

If you write material for mobile devices, you’re faced with another set of challenges. How can you help mobile customers find what they need quickly? This Klariti tutorial explains how.