5 Writing for the Web #
Create engaging and informative content that helps your audience and is optimized for the Web.
5.1 Topical structure #
The most important thing to do with your Web copy is to help users get answers to their questions as soon as possible. To achieve this, we recommend the modular approach of topic-based authoring where documentation is created and maintained in chunks, subsequently referred to as topics.
Topics have the sole purpose of supporting users in their tasks. Each topic focuses on one specific subject and has one distinct purpose. We write topics in a way that they can stand alone as well as in context with other topics. They should also be reusable in different contexts.
Recommendations:
Put your most important information first. Users typically decide if they are going to stay on your page within 3–5 seconds. Make sure your copy helps users understand the big picture right away.
Write for scanners. Help readers find the answer to their question. Create headlines that are clear and to the point. Break long headlines into a heading and sub-head. Ask yourself: Is it easy to see the benefit of the page with a quick glance?
Organize content logically. Layer and break up your content into sections to help users find answers at a glance.
5.2 Writing SEO-friendly content #
SEO, or Search Engine Optimization, is the strategy to attract organic (unpaid) traffic that originates from online search and refers to visitors landing on the Web site. When it comes to SEO, content is key. Here are some insights to help you create and design the content that will rank high in search engines.
- Brainstorm and research keywords
To learn what type of content search engines deem best for a specific keyword, search the phrases you want to rank for. Bear in mind the approved SUSE documentation terminology.
At the same time, do not stuff your content with keywords. The keyword ratio for an article should be 2–4%, that is, 8–10 keywords per 500 words.
- Structure your content in a way that is easy for users to scan
Structuring your headings in a hierarchy can make a larger content piece easily scannable while helping search engines understand the context of your content. For example:
<H1> Dealing with Boot and Installation Problems <H2> Problems Booting <H3> Solution 1 <H3> Solution 2 <H2> Problems Installing <H3> Solution 1 <H3> Solution 2
- Create concise and meaningful title tags and meta descriptions
Search engines pull the title tag, or meta title, from H1, and the meta description from the abstract. The number of characters is limited, and the recommended length for meta titles is 55–65 characters. However, they must not be shorter than 29 characters. Be sure to optimize your headings wherever appropriate by integrating keywords, such as product names, into them. The optimal length for meta descriptions is 145–155 characters.
Product names are known for their extra length, so effective page titles and meta descriptions may require the use of abbreviations. From the search engine perspective, it can be helpful to mention the abbreviation within the content by adding the abbreviation in parenthesis after the first use of the term.
- Link from (and to) your content
Links are critical to establishing the authority and relevance of your content. The two most important types of links are:
Internal links lead to and from other pages within the same domain and help establish the relationship between two pieces of content. Internal linking helps search engines discover new pages on the Web site and index them.
Inbound links lead to your content piece from a different domain (for example, SAP.com to SUSE.com).
External links to high-quality, creditable Web sites help increase the validity of your own Web site. The better the links, the higher the page ranks in search results.
- Optimize images by adding alt text
Be sure to add alternative text whenever you use images. This practice allows search engines to understand the context of your images and index them more accurately. It also improves the accessibility of the Web site.
5.3 Writing for a global audience #
Remember that every document is a potential candidate for localization (translation). Make sure the document’s original English content is correct and clear. Simplicity, clarity and direct prose are essential.
Recommendations:
Keep sentences short. Shorter sentences help translators and target audience to better understand the content.
Be consistent. Stick to the terminology and use the same sentence structure for similar content. Use the same sentences for repetitive texts. This helps to improve the translation memory leverage.
Use proofreading and review options. Have your content reviewed to detect misunderstandings in advance.
Keep it clear. Make clear statements and avoid “should,” “could” and similar unprecise words.
Mark non-translatable text. Use tags as defined in Chapter 8, DocBook tags or use the ITS tag feature to mark all content that should not be translated (for more information, see Section 8.2, “Using ITS tags”). Use entities for product names, example names, etc. Always mark code as such so that it is not translated.
Write for the world (if possible). Do not use country-specific words and examples. Use common international examples instead.
Use only as many graphics as needed. As each graphic or screenshot needs to be localized as well, keep it to the minimum.
Do not break sentences. Do not use hard breaks within a sentence.
Do not break your sentence with lists. For example, do not structure the phrase like this:
You can use the following commands: -a -z -b to start the system update.
Keep the sentence together instead:
To start the system update, you can use the following commands: -a -z -b