How We Write For The Web

This is the writing guide that Marmelab employees read when they join the company. It explains what we expect in this blog, which editorial choices we made, what we consider a "good" article, and how to write one. Ready?

I (François) love writing. I also love reading articles. Over the years, I have gathered writing techniques that were used in many of the articles and blogs that had an impact on my work. These techniques help me write better articles and get more attention. I suggest you follow these tips to ease the reading experience of your colleagues (and fellow readers around the world).

Use The Inverted Pyramid

Build your article for people who spend 2s, 10s, 1min, or 5min reading it. This means that:

• People who only spend 2s on your article will only read the title. It should contain the essential information, it should be short and catchy.

'GreenFrame: Measure Website Carbon, Improve Dev Practices'

is better than

'Why We Built GreenFrame' or 'GreenFrame: Measure The Carbon Footprint Of Software, Improve Developer Practices'

• People who spend 10s on your article will read the excerpt in addition to the title. It should contain additional information (and not repeat the title). Together with the title, it should fit in a tweet.

Excerpt: We've built a tool measuring the energy consumption of web apps to help reduce the environmental impact of developers. See how it works in this preview.

is better than

Excerpt: We are developers who care for our planet, and we want to measure the environmental footprint of the software we develop. But in order to do that, there are many difficulties that one must overcome. We started by building a proof-of-concept.

• People who spend 1min on your article will read the section titles and the images. If your article doesn't have those, they won't be tempted to read further. The section titles should be descriptive and summarize the section.

Macroscopic View: Servers Emissions Are Negligible

instead of

Macroscopic View

• If the reader likes the title, the excerpt, the section title, and the images, they may proceed to read the text. This concerns roughly 20% of readers. So spend enough time ironing out the essentials.

Reference: Inverted Pyramid Style of Writing for Web – The What, Why & How

Be Human

You probably had problems with the experience you write about. Don't hide these problems. Don't make it so your reader thinks you've achieved something incredible without any bumps. Include your hesitations, trials, and errors. You can even include feelings. This will help readers to identify with you.

At first, I thought Docker would help me run my Node.js apps everywhere. I was wrong, and I learned it the hard way. But now I can at least run a container on AWS.

instead of

Docker is the best way to run a Node.js app.

Also, you are not exceptional. Your opinion isn't gold. It's just that: your opinion. Don't be too prescriptive.

I find it useful to use the same make commands across every project

instead of

Use the same make commands across every project

The best articles, in my opinion, are the ones that tell a story. A story has a beginning and an end, and the main character changes during the course of the story. So don't hesitate to use the following plan:

1. I have a problem
2. I tested this solution. It didn't work.
3. I found a new solution. It worked.
4. I'm sharing it with you because you may have the same problem

Finally, tech articles are usually boring. You are not boring. Write the same kind of articles you'd like to read. Include puns, twists, and fun.

"Easy" Is Forbidden

"Easy" usually means "hard" for your readers. Except that when they read "easy", they feel diminished. So be kind, and remove all absolute judgments about how simple something is. Speak about your experience, be factual.

I needed to paste 3 commands to install the project

instead of

Installing the project is simple

Summarize Your Opinion In A Conclusion

If the initial excerpt summarizes the facts, the conclusion is a great place to summarize your opinion.

For instance, you may write an article describing how to apply a certain library to solve a particular problem. You can take advantage of the conclusion to explain if you liked it, how it compares to other solutions, and when you would recommend it.

Also, the conclusion is an opening. If you had to do more work to explore the subject further, where would you go? Think of it as an invitation for your reader to take over.

Make It Short

If a paragraph is long (more than 3-4 sentences), split it into several paragraphs, or use bullets and number lists.

If a sentence is long (more than 25 words), split it into several sentences.

If your article is long (more than 10 minutes to read), split it into several articles.

Also, people receive tons of notifications, emails and RSS feeds and rarely read more than the excerpt. By splitting an article into several parts, you will actually increase the number of people who read your content.

Put Lots Of Images

Our brain is much better at understanding images than text. So while proofreading your article, try to find occurrences of text that you can turn into a chart, a diagram, or a sketch. It doesn't have to be a complicated diagram:

Screenshots are fine, too. Screencasts are even better.

Try to find existing copyleft images that replace your text. If you can't find one, draw it with tools like Excalidraw or draw.io.

There should be a rhythm of about 1 image per page. In an article with fewer images, readers get desperate by all the text and leave. In articles with more images, readers skip the text.

If you don't have enough content images to keep that rhythm, complete your article with illustration images. Check copyleft image banks like Unsplash for illustration images.

Prefer images with people to images with objects.

Write Titles In Title Case

In English articles, the article title and all section titles should use Title Case.

GreenFrame Measures The Energy Consumption Of A Digital System

instead of

GreenFrame measures the energy consumption of a digital system

In a French article, only the first letter of a title or a section title is capitalized.

Show, Don't Tell

Write as many examples as possible. Sometimes, an example is enough, you don't even have to explain it.

If your post talks about coding techniques, write it with code.

Don't write that your technique increases usability: show a before / after screencast and let readers judge by themselves.

I, We, You... Pick One

Preferably, write your article using the 1st person ('I'). It makes it more personal. If this is the work of several people, you can use 1st person plural ('We').

To make the project easy to run by anyone, I always write a docker-compose.yml

To make the project easy to run by anyone, we always write a docker-compose.yml

Or you can write it in an impersonal way, never saying I or We, using imperative tense and starters like "let's". But try to avoid being too imperative, and don't hesitate to nuance your orders with a "should" or a "may".

To make the project easy to run by anyone, always write a docker-compose.yml

To make the project easy to run by anyone, you should write a docker-compose.yml

But the most important rule is: choose one form and stick to it during the entire article. Never mix "I" and "We" and "You" in a single article.

Users May Be Women, Use Plural Or "They"

In French, users are men by convention. Not in English.

When a user presses the start button, he sees the start menu.

This will be considered offensive by English readers. When you write about indeterminate users, alternate between "He" and "She", or better, use singular "they":

When a user presses the start button, they see the start menu.

Yes, it sounds incorrect to use a plural pronoun for one person, but it is correct in English.

But the best trick to avoid caring about He/She sentences is to use the plural form:

When users press the start button, they see the start menu.

Use The Active Voice

Passive sentences are harder to read. They sound more "arty", but they don't have their place in a tech blog. Prefer the active form.

We built the feature to ease user input

instead of

The feature was built to ease user input

Prefer The Present Tense

Articles written in the past tense are harder to write and harder to read. With the present tense, you make them more immediate, more vivid.

Let's add a higher-order component to reuse the logic

instead of

I added a higher-order component to reuse the logic

Use A Spellchecker

This may be the most important rule. Some readers, like me, stop reading at the first typo they meet. I tend to think: if the writer didn't pay attention when writing, why should I pay attention to the text?

Also, don't expect that your typos will be spotted during the review. It's not the role of the reviewer (just like code review shouldn't be used to discuss tabs vs spaces), they don't have time for that. It's your duty, as a writer, to produce a text exempt from faults.

Use grammarly.com for English articles. Don't install the browser extension, though: it's a keylogger.

I used Grammarly on this piece of content before publishing it. It helped me fix 27 mistakes.

Editor's Notes

I spend a lot of time proofreading (and sometimes reshaping) articles before publication. I tend to write more comments during an article review than during a code review. Don't be offended: it's also a way to harmonize the blog content and to guide you towards the style and the content I want for the Marmelab website.

And if you don't agree with these tips for a good reason, then fine! Prove that you don't need them by writing a kick-ass article.

Inspirations

The most popular articles in the Marmelab blog tend to follow these rules. (Re-)Read them to get inspiration:

• Sunsetting PHP Faker
• Handling JWT in Admin Apps the Right Way
• Marmelab est lauréat du Challenge Sobriété Numérique 2020
• Build Augmented Reality Applications With React-Native

Note that all the articles above are too long. They would have got more readers if cut into 2 or 3 parts.

Conclusion

These guidelines actually work: The Marmelab blog has a great reputation and contains some very popular articles. Most of all, it's a place where we are proud to publish because our articles are displayed close to other articles that people love. I often meet people who mention an article they read in our blog, and who want to know us better because of that.

Not all the articles in this blog are memorable, but they are all equally important to us. They illustrate our values of curiosity, knowledge sharing, pragmatism, diversity, and transparency.

The amount of time we spend on this blog is excessive. For a small company like Marmelab (15 employees at the time of writing), spending that much time on sharing what we know with the rest of the world sounds like a bad investment. We do it because we love it. We do it because it helps cast some light on the work we do, and it helps us build more satisfaction in our job. We do it because that fulfills some needs that are at the very top of Maslow's Pyramid.

Let's write a good blog, together.