This document outlines a rough process that should be followed when writing a new article for our website. This process is not set-in-stone, and it is fine to deviate from it when there is a good reason to. The purpose of having a process is to:
Here is a high-level description of the process, which should be followed in order. We recommend writing out your steps as you go (see this file for an example).
Why do we write articles?
Good general topic areas include:
We write articles for a few different audiences. Here is a brief list, sorted in order of highest business value to lowest business value:
Feel free to propose other audiences, but David or Yujan may veto it if it is too far outside of our usual domains.
Knowing your audience is important. Your audience’s experience with your topic will help you decide what background material to include in your article. For example, if your audience is experts familiar with a language, then you may decide some background information would be tedious and distracting to include.
One of our goals for writing articles is to increase our search ranking. One way we do this is by selecting keywords.
Here is a non-exhaustive list of keywords that are worth targeting:
A good way to include keywords in technology-focused articles, is to reference examples from client projects or our open source projects.
Ideally you will include keywords in the title or the headers.
It is usually good to write out a two-level outline. The top-level should be the section headers for your article, and you should have 3 - 6 of them, depending on the length of your article. If the article is short, it may not make sense to include headers, but usually it does. Headers help people skip the article.
Supposedly, only 16% of people will read the article—everyone else will just scan it.
All figures must be created in Figma in the same document.
Good articles are:
The Federal Plain Language guidelines have a great section about writing for the web.
People use the internet to easily find, understand, and use information to complete a task. Unlike print media, people do not read entire web pages. They scan instead.
Good web content uses:
The inverted pyramid style. Begin with the shortest and clearest statement you can make about your topic. Put the most important information at the top and the background at the bottom.
Chunked content. Don’t try to pack everything into long paragraphs. Split topics up into logical sections separated by informative headings.
Only necessary information: Use only the information your users need to achieve their tops tasks. Omit unnecessary information.
The Nielson Norman Group has many good articles about writing for the web. Here are some useful links: