Writing for the web
Jump to navigation Jump to search
Writing for the web is easy. Follow these few simple guidelines and it will help to keep standards high and make the wiki's content easy for people to read and take in.
- Put the most important thing first. On the web people typically decide within six seconds whether they are going to stay on the page, so you need to get to the point straight away to keep them.
- Write in Plain English so that everyone can understand what you are saying.
- Write in good English - poor grammar helps no-one.
- Refer to the Plain English campaign's free guides on writing in good, Plain English.
- You may be fascinated by every tiny detail, but your audience is probably interested in a specific question or in generalities. Link through to other documents for the serious details.
- If its complicated, simplify it - this doesn't mean dumbing it down, but breaking it up. Use categories, sub categories, and multiple pages rather than one very long page that is hard to digest. Refer to the styleguide and think about how to do this.
- Use "contextual links" - like the ones on this page.
- Never use click here.
- If you link to a document, include as part of the link its type in brackets such as "example link (.pdf)"
- Use headings for headings, and bold for emphasis. Don't use italics for emphasis.
- Use italics for languages other than modern English, and the titles of books/publications only.
- Numbers up to ten, and at the start of a sentence should be given in words. Other numbers are given in numerals, until you "come 'round" again to one thousand (but then 1,001 comes next up to two thousand etc.)
- Dates are assumed to be AD unless BC is specified - but you can say AD if you like. Not a rule as such, but "modern" or "PC" styles such as BCE annoy +Wiglaf and if he sees them they will be removed.
- If you have a specific date-range in mind, please specify it. "Viking age", "Iron age" and "pre-Christian" will mean different things in different countries, which can lead to confusion. If in doubt, please clarify, e.g. "in the earlier viking age (9th century)".
- Use a numbered list only for instructions or when order matters.
- At any other time when you might use a numbered list, don't. Use a bullet point list. Bullet point lists can be a good way of conveying a series of facts (or rules) quickly.