Writing for the web
Good content is easy to read and understand. It also helps users digest and find information quickly by using:
- Headings and subheadings
- Short sentences and short paragraphs
- Plain English and conversational writing
- Bullet points
- Keywords
Accessibility and web standards
- Link text should describe where the link will take you. You shouldn’t tell users to use the links on the left or click here. Describing the destination is an accessibility requirement and provides a better user experience. Also, because users can navigate a page using hyperlink text, it’s important to use descriptive link text that you can read out of context.
- Correct: Read more about making link text meaningful.
- Incorrect: For more information on meaningful link text click here.
- Use italics sparingly as they’re hard to read online.
- Don’t underline text. On the web, underline = link.
- Use all caps sparingly. Research shows all caps is harder to read than sentence case.
- Avoid exclamation points as they can look unprofessional. We always use one after Happy deployments! but should be sparing otherwise.
- Write in an inverted pyramid style. Place the most important information at the top, extra information toward the bottom.
Knowing the audience
Understanding our audience helps us consistently provide useful content. Before writing, ask yourself:
- Who are we writing for? How much do they know about the topic?
- Fill gaps in their knowledge
- Solve their problems
- Know how much technical terminology to include
- What do they want? What's their goal?
- Looking for facts
- Trying to understand the subject
- Trying to decide whether to interact with us
- Making up their minds about Octopus Deploy
- What do we want? What impact do we want this content to have on the reader?
- Drive traffic
- Encourage conversions like sign-ups or sales
- Increase awareness
- Encourage contact with a specific department like sales
You need to combine the answers to these questions to provide useful content. This gives readers what they need in the right way while supporting our business goals.