Article Process

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:

Outline

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).

  1. Pick a topic
  2. Pick an audience
  3. Pick 3 - 5 SEO keywords
  4. Run topic, audience, and keywords by David or Yujan
  5. Research topic, writing notes
  6. Write an outline
  7. Pick 1 - 3 planned figures + write captions
  8. Write your article title
  9. Run your research notes, outline, figures + captions, and title by David or Yujan
  10. Write rough draft between 400 - 1000 words
  11. Generate the figures
  12. Run through Grammarly (should have close to a perfect score)
  13. Run by David or Yujan
  14. Send to our copy editor
  15. Once approved, push online

Motivation

Why do we write articles?

  1. To demonstrate to sales leads, who may be looking at our website, that we are expert software developers.
  2. To educate developers (and business owners); some of these developers may be current or future Innolitics team members.
  3. To improve our search ranking.
  4. To learn; you will probably learn something about the topic you are writing about as you research and think about it.

Topics

Good general topic areas include:

Audience

We write articles for a few different audiences. Here is a brief list, sorted in order of highest business value to lowest business value:

  1. CTO or technical CEO at a medical device startup
  2. Experienced developers in the medical device domain (including other members of Innolitics)
  3. Experienced developers
  4. Less experienced developers

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.

SEO Keywords

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.

Outline

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.

Figures

All figures must be created in Figma in the same document.

Draft

Good articles are:

  1. Correct
  2. Useful
  3. Succinct

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:

Technical Details

Style Guide