Article Writing Process 🔗

This document outlines how to contribute articles for our website.

This process helps us:

Motivation 🔗

We write articles to share knowledge (part of our company mission) and continue learning (one our company values).

More specifically:

  1. Individual Learning – Writing about a topic is one of the best ways to learn about it
  2. Sales – Sales leads will see that we are expert software developers
  3. Marketing – Content will improve our search ranking, helping clients find us
  4. Team Learning – To produce educational resources for other developers on our team

Outline 🔗

Here is a list of the activities involved with publishing an article.

You may work on the article in a separate markdown file or in a branch in our website’s Github repository.

Write out the outputs of each activity in a draft markdown file. See this file for an example).

  1. Topic
  2. Audience
  3. Checkin (optional)
  4. Outline
  5. Plan figures
  6. Checkin (optional)
  7. Draft article
  8. Title
  9. Figures
  10. Copy editor review (optional)
  11. Final checkin
  12. Publish!
  13. Link building (optional)
  14. Updates (optional)

1. Topic 🔗

Good general topic areas include:

2. 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 software domain (including other members of Innolitics)
  3. Experienced developers
  4. Less experienced developers

Feel free to propose other audiences, but it may be vetoed if it is too far from our usual domains.

Your audience’s familiarity with your topic will determine what background material to include. 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.

3. First checkin 🔗

The purpose of the checkins are to make sure you don’t spend too much time working on an article that isn’t appropriate for Innolitics’ website. If you know that an article is relevant (e.g., perhaps because David suggested writing it), then feel free to skip this step.

Assign David or Yujan to a PR with your draft markdown file (or email it to them).

4. 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 skim the article. Supposedly, only 16% of people will read the article—everyone else will just scan it.

5. Plan figures 🔗

Almost all articles should have at least one figure. Many online readers skim and focus on the figures and their captions. Thus figure captions should be somewhat standalone.

What figures do you plan to include? What will their captions say?

Select a main image or figure which will act as the title-image for the page which will be visible when links are shared on Twitter, Slack, and social media sites.

6. Second checkin 🔗

This checkin is also optional, although highly recommended to avoid having to rework content in the final review.

Assign David or Yujan to a PR with your draft markdown file (or email it to them).

7. Draft article 🔗

It is okay if the outline changes as you write the draft.

Qualities 🔗

Good articles are:

  1. Correct
  2. Useful
  3. Succinct

We recommend On Writing Well, by William Zinsser. The first ten chapters are especially helpful.

Technical details 🔗

Style guide 🔗

We use the oxford comma (i.e., “a, b, and c” vs “a, b and c”).

We do not wrap em-dashes (—) or en-dashes (–) with spaces (i.e., “–” vs “ – “).

We use commas after the “i.e.” and “e.g.”.

We use title case for titles (e.g., “Formatting Articles”) and sentence case for headers (e.g., “Heading grammar”).

Avoid inline code snippets in heading text. The two styles often clash, and omitting the snippet is consistent with other style guides such as MDN and O’Reilly.

Code block syntax highlighting can be enabled by following the initial three backticks with the language identifier. For example, open a code block with ```typescript instead of just ```.

Place images within figures. E.g., see this article. Do not abbreviate the word Figure to Fig., as is often done in academica papers. The figure caption text should begin with “Figure XYZ:” (as opposed to “Figure XYZ - “).

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.

Run your article through Grammarly (it should have close to a perfect score).

Resources 🔗

The Nielson Norman Group has many good articles about writing for the web. Here are some useful links:

8. Title 🔗

The title should explain what the reader will get out of the article; it should answer the question “what is in it for me?”

9. Figures 🔗

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

10. Copy editor review 🔗

This activity is optional.

Ask David how to get in touch with our copy editor.

Iterate with the editor to polish and fine-tune the language. (Their suggestions may also be a good opportunity to strengthen your writing.)

11. Final checkin 🔗

Run the polished article by David or Yujan! Nice work! This review is required and will be the most in-depth.

12. Publish 🔗

Move the article over from the “_drafts” to the “_posts” directory and prepend the date (see other articles in “_posts” for examples). Then push to master!

This activity is optional.

It is helpful to find ways to promote your article online. Some good places to promote your article are:

Be sure to follow each website’s guidelines—usually this means providing real value in your comments and not just spamming.

14. Updates 🔗

This activity is optional.

Watch the Google Analytics reports for your article. If you can see a lot of people are coming to the page from a certain location, it may make sense to optimize your content appropriately.

Also, if you refine your thinking after the article is published, please update the article.