How to Write Great Web Development Articles and Tutorials

As some of you probably already know, since January 2014 I’ve been working for SitePoint as one of their Managing Editors, mostly editing HTML, CSS, and Sass content. I’ve also helped out with Mobile content, JavaScript, some general Web stuff (Git articles, build tools, and other generic content), and I write SitePoint’s primary newsletter each week.

I love my job at SitePoint—it’s the best job I’ve ever had. As long as SitePoint still wants me working for them, I hope I can continue to help them put out better and better content for front-end developers.

I’ve rejected or sent back for editing quite a few articles since I’ve started my editing duties. Many of those rejections suffered from the same problems. So for this post, I’ve put together my thoughts on what I think makes for a good web development article or tutorial.

Some Opening Remarks

Before getting into the meat of this, let’s get a few things out of the way:

• Not everyone will agree with me on all these points.
• I’m not writing this because I think I’m better than others. We all have our strengths. I’m not perfect. I could name 100 developer/writers who are better than me.
• Many of the items in this post are from a document I’ve been compiling for some time now, and which I’ve passed on to authors who write for SitePoint, to help them improve.
• Many of these tips apply to any kind of writing, not only technology or development.
• My views in this post do not necessarily represent those of SitePoint or its management. The editors at SitePoint have a lot of freedom to shape the content, but it’s still subject to SitePoint’s guidelines, which might differ from my own as stated here.

With that somewhat dragged-out introduction (more on that later!), let’s get to the main points.

Add Links to Support Statements

Articles should almost always have reference links. If you’re writing about front-end technologies, your content should generously link to stuff like:

• W3C Spec
• MDN’s reference
• Authoritative articles by respected members of the community
• Good articles by the same publisher that you’re writing for (preferably not really old ones).

If you’re discussing a particular tool or technology (like a specific jQuery plugin or a CSS Preprocessor), your first paragraph should always link to the home page for that technology. This is especially true if you’re talking about a new tool or technology or one that’s not as well known. In some cases, if the tool is common in context (like Sass on a blog about Sass), then you’re probably fine not including a link to Sass’s home page.

You should also include links to support certain kinds of statements made. For example:

• “Google considers page speed in SEO rank.”
• “Studies show people scan websites, they don’t read them.”
• “Flexbox is supported in IE11.”
• “Hamburger icons are bad for usability.”

All the statements above (and similar) should be sourced. Especially if you’re talking about a controversial subject where people are going to debate you. Some statements, however, are opinions. If that’s the case (e.g. the 4th point above), then you should clearly state that this is your view, and give reasons why.

As an example, this article on accessibility mentions some case studies. Notice the studies aren’t only discussed; they’re sourced with links.

Link to Documentation

Related to the point of linking to sources, if you’re talking about specific features in Bootstrap, or Sass, or another tool or framework, you should link to the sections in their documentation that you’re discussing. For example, if you’re talking about Bootstrap’s Jumbotron component, link to it.

Sometimes I get the feeling that authors are afraid to link back to a tool’s docs because they feel they will be “revealing their research secrets”. Maybe I’m wrong, but that’s how it seems.

Linking back to specific parts of documentation helps the reader to have some extra stuff to look into should the need arise. And it shows that you respect the authority of the official docs for that tool, and this gains a reader’s respect.

Link to the Latest Version of Specs

I’ve made this mistake myself a few times. If you are talking about, for example, Flexbox, you might search for the spec and find a link like this:

http://www.w3.org/TR/2014/WD-css-flexbox-1-20140325/

But that’s a static version of the spec that won’t change. What you want is the permanent link to the current version of the spec. So make sure the URL looks more like this:

http://dev.w3.org/csswg/css-flexbox/

Sometimes, unfortunately, a Google search will bring up a “snapshot” version first. You’ll be able to tell by the URL.

Also, I think the “dev” version (which is usually called the “editor’s draft” of the W3C spec) should be linked to more often than the non-dev version. Usually the differences are small, but the dev version is always more up to date (although it’s also more in flux).

Always Try to Include a Demo

For front-end technologies like HTML, CSS, and JavaScript, there is usually no excuse for not including a demo with whatever you’re talking about. Naturally, there are some cases where a demo is of little value. An article about semantic HTML is one example. A Sass article also may not benefit from a demo.

Believe it or not, I’ve edited articles that included a screenshot of the technique being discussed, but not a demo. That’s kind of like giving someone a picture of a hamburger for dinner!

For demos, some useful tools are:

• CodePen
• JS Bin
• JSFiddle
• SassMeister

The last one in that list, SassMeister, can be used when it’s not necessarily a visible demo, but a code concept or technique where you want to see the compiled output.

When coming up with ideas for articles or tutorials, try to go with ideas that will work well with demo pages. Those are often the best and most popular articles.

Include a Brief But Effective Introduction

Too many authors write intros that basically amount to “filler” content. Here’s an example of a bad introduction:

Front-end developers have been trying many different frameworks in recent years. Bootstrap is a really popular framework, and it has many tools you can use today. We no longer need to scratch our heads wondering how to create a cross-browser drop-down menu, or a responsive grid, or a tab switcher. Bootstrap can do it all. But how accessible are its components? In this post, I’ll show you how to take Bootstrap to the next level by making your Bootstrap website more accessible.

Notice all the unnecessary fluff leading up to the main point of the article about accessibility? Instead, the following is better:

Bootstrap is the most widely-used framework in the world. But a common complaint I hear is that its markup is unsemantic and inaccessible. Let’s use two Bootstrap components as examples to see if we can remedy this.

This intro is clear, it presents exactly the problem you’re going to solve, and it gets right into the meat of the post, which is how to make a Bootstrap website (or component) accessible.

In brief, a good intro has two necessary ingredients:

• Present a problem to solve
• Tell us briefly how you will solve that problem

Then get right into it. Chris Coyier of CSS-Tricks is the master of introductions. He doesn’t waste any time, he immediately tells you what problem he’s facing and how he’s going to consider solving it. This recent post is a perfect example of that. No rambling, no wasting time, straight to problem/solution.

Write Tool/Technology Names in the Correct Format

Sometimes it feels like 90% of my edits are correcting “JQuery” to “jQuery”; “SASS” to “Sass”; “Github” to “GitHub”; or “AJAX” to “Ajax” (believe it or not, it’s not an acronym!). This is especially necessary if you’re talking about an obscure technology or a new tool by a startup that’s trying to establish a brand.

Do the necessary research. Take five seconds to look at the official website or GitHub repo of the tool you’re discussing and make sure you get the casing and/or spacing right. If MailChimp calls itself “MailChimp”, don’t write it as “Mail Chimp”, “mailchimp”, or “Mailchimp”. In some cases, even the official website itself will use different casing for the name of the technology. If that’s the case, I usually pick the one that’s in the website’s title element.

By writing tool names properly, in the way the creators intended, we show respect for these tools and we help to represent their brands correctly in our writing.

Don’t Try to Sound Professional or Formal

The best articles are the ones where the author talks to the readers in his/her own voice. Imagine you’re having a conversation with your good friend at a web conference. You would never say something like this:

“Flexbox has numerous features that developers can avail themselves of in order to help their layouts be on the cutting edge and avoid legacy practices.”

That’s not too inviting. Instead you would say something more natural, like:

“We’ve used Float and positioning hacks for years in older browsers. Flexbox makes all of that so much easier.”

Of course, there’s balance needed here. You don’t want to sound so informal in your writing that your readers are annoyed. Keep it loose and be yourself, but don’t be too crazy.

Also, try to avoid pretentious Shakespearean-sounding words like “whilst” or “hence”. I know that some of these words are common in certain parts of the world, but remember that on the web you’re writing for a larger audience, so “whilst” can always be replaced with “while”, and “hence” can be replaced by something less-pretentious like “therefore”.

Similarly, I’ve never found a sentence that benefited from the expression “the former… and the latter”. For example:

CSS and HTML have been around for years. The former for 20 years; the latter for 24.

This former/latter expression is irritating to read, especially in a more complex sentence. The following is easy enough to write and understand:

CSS has been around for 20 years and HTML has been around for 24.

As mentioned, it’s all about simplifying and asking yourself “Would I say this in a face-to-face conversation?” If the answer is “no”, then you might want to rework the sentence. But again, this doesn’t mean you should write like you talk. It should be natural and conversational, but a little more formal than your everyday speech.

A Hyphen is Not the Same as a Long Dash

There are a lot of general writing and grammar tips like this one that I could include in this post, but I feel like this is the one that people most commonly get wrong. The following is not correct:

Sass is a great technology ‐ albeit a difficult one to learn.

This is correct:

Sass is a great technology — albeit a difficult one to learn.

Hyphens are used for math, phone numbers, breaking words onto new lines, in compound words (e.g. “accident-prone” or “five-column grid”), and so on. But they shouldn’t be used at the start of an interjection in a sentence. That’s where you need a long dash. You can copy and paste a real long dash (—), or you can use the character entity, —. Also, most style guides recommend no spaces before and after the long dash, although apparently it’s not a hard-and-fast rule.

On a related note, you might want to read through this Bootstrap issue where a similar topic was discussed, showing the proper use of a hyphen and the two kinds of dashes.

Headings Alone Should Develop the Theme

A reader should be able to read the title of your post, then read each of the primary headings in order, and get a good higher-level understanding of the subject being discussed.

To do this, your headings should be clear in stating which part of the article is now being developed and they should not be general or vague.

Imagine you were about to read an article on making a Bootstrap site accessible. Here is an example of bad headings:

<h1>How to Make Bootstrap Accessible</h1> 
  <h2>Why?</h2>
  <h2>Suggestion #1</h2>
  <h2>Suggestion #2</h2>
  <h2>Suggestion #3</h2>
  <h2>Conclusion</h2>

The headings in that example tell you nothing about how the content will be developed. Here’s the same example improved:

<h1>How to Make Bootstrap Accessible</h1>
  <h2>Why is Bootstrap Inaccessible?</h2>
  <h2>Use ARIA Roles</h2>
  <h2>Use Semantic Tags</h2>
  <h2>Use WAVE to Test Accessibility</h2>
  <h2>Conclusion</h2>

Now the content being discussed is much more clear and inviting.

On a similar subject, you don’t need a heading called “Introduction”. Your introductory text will be the introduction. You’ll notice that my “improved” example above includes a heading called “Conclusion”, which is just as vague as “Introduction”. But that’s okay. This serves as a signal that the article is coming to an end, so I think it has some value.

Don’t Say Things Like “It’s Easy” or “It’s Very Good”

If something is “easy” or “very good” your readers will decide based on the evidence you present. Not everyone is at the same level. If you’re writing an article about the command line, and you say stuff like “It’s easy, simply type git [whatever]”, you’re going to alienate many readers.

Even the simplest CSS and HTML topics are not “easy” to some people. So avoid sentences like that. This is true in a lot of other cases too. Here are some examples of bad ways to write things:

Bad:

Git is an easy tool to use to assist with version control.

You don’t have to tell the reader it’s easy; instead, explain why it’s easy. In other words, describe in detail what makes it easy, but don’t tell them that.

Another bad example:

Bootstrap is powerful and useful.

That sentence says nothing. Instead, say something like this:

Bootstrap can help you get any project off the ground fast, and in a cross-browser fashion.

In many cases I see authors writing both of the above sentences, one after the other. You don’t need the first one. The reader will see the “power” and “usefulness” in the explanation itself. And what if the user doesn’t think it’s “useful” or “powerful”, even after that explanation? Well, that’s up to them.

But balance is needed here too. You can tell readers you love something or that it’s cool, but say it in a context where it has some value, otherwise it amounts to nothing but filler.

Avoid Vague Words Like “very” and “really”

Further on this point, 99% of articles could do a find-and-replace on all the following words and it likely wouldn’t change anything about the article:

• very
• really
• just
• literally
• honestly
• actually
• certainly
• absolutely
• surely
• truly
• in fact
• simply

But again, balance is needed. Sometimes these words can serve as a way to make things a little more natural and conversational. But don’t overuse them (especially the first three). In almost all cases, you don’t have to say how “very useful” something is; instead, tell your readers why it’s useful.

Don’t Alternate Between “we” and “you”

In a tutorial, you might be talking the user through a series of steps. So you might say something like:

“We will put the HTML tag in here with a custom class”.

But later in the article you might say:

“You can remove that class now.”

Notice how you’ve switched the viewpoint? If you start out talking about what “we” are doing, stay with “we”; don’t switch to “you”. I’ve even seen this switch take place in the same sentence!

We will put the HTML tag here because you want it accessible.

So be consistent:

We will put the HTML tag here because we want it accessible.

Have Consistent and Easy-to-Read Code Blocks

When including code blocks in articles and tutorials, I have a few general rules:

• No horizontal scrolling
• Consistency in syntax and whitespace
• No single line CSS

The following is a bad example of a CSS code block:

.example{
  float:left;
  color:blue;
}

It’s subtle, but here is the same example corrected:

.example {
  float: left;
  color: blue;
}

The difference might not be significant in the above comparison, but it’s much more clear when using multiple code examples on a single page, with longer code blocks. So don’t forget the space after the colon for property/value pairs, as well as the space after the selector and before the opening curly brace.

Further on this, I don’t like CSS that looks like this:

.example
{
  float: left;
  color: blue;
}

Always put the opening brace on the same line as the selector. This should be done in JavaScript too, in function syntax.

As mentioned, don’t do single-line CSS, always use multi-line code blocks. Even if you prefer single-line in real projects, that’s fine. They’re not wrong to use in production. But they are not as readable in tutorials and articles, so always use multi-line CSS blocks.

In line with the no horizontal scrolling rule, try to avoid overly long lines of code. So let’s say you have the following HTML:

<link rel="apple-touch-icon-precomposed" sizes="114x114" href="/images/apple-touch-icon-114x114-precomposed.png">

You can improve the readability of that by writing it like this:

<link rel="apple-touch-icon-precomposed"
      sizes="114x114"
      href="/images/apple-touch-icon-114x114-precomposed.png">

You can do something similar with long selector groups or long CSS transition declarations. So instead of this:

.example, example2, .example3, .example4, .example5, .example6, .example7, .example8 {
  transition: color 3s linear, width 2s ease-out, height 3s ease-in, border-width 1s linear;
}

You can do this:

.example, example2,
.example3, .example4,
.example5, .example6,
.example7, .example8 {
  transition: color 3s linear,
              width 2s ease-out,
              height 3s ease-in,
              border-width 1s linear;
}

No Walls of Code

If any code block is longer than 10 or 15 lines, then you’re probably doing something wrong. To fix this, you can try one of the following:

• Remove any unnecessary parts of the code. I can’t count the number of times I’ve removed the “doctype” from a code block. Not to mention other things like an entire <head> section, which might include meta tags and other elements that had nothing to do with the article.
• If you’re talking about one specific CSS feature, don’t include all the styles you apply to the element being affected with that feature. For example, when talking about transitions, only include the transition property along with some other relevant stuff (like the properties you’re transitioning). Don’t include stuff like “float: left” or “margin: auto” that have nothing to do with the transition. Tell the reader that common CSS is removed for brevity and only include the necessary code.
• If, for whatever reason, your code must be lengthy, then you can add a bullet list below it to describe what’s happening step by step.
• If possible, break the code block up, discussing it in steps, then (if you must) include the completed code at the bottom of the section or article, and indicate clearly that this is the completed piece, with any relevant demo or code hosting links.

The Best Article Topics are Specific

Articles that are popular and easy to follow are ones that are specific rather than overly general. Here are some examples of article/tutorial ideas that are far too general and are likely not going to be too popular:

• Building a Website with Foundation 5
• An Introduction to Git
• Building a Responsive Website with jQuery Mobile

Those are decent ideas, but unless they are comprehensive and well written, they are likely not going to get much traffic or generate much buzz.

Here are some better ideas:

• How to Create Off-canvas Navigation with Foundation 5
• Installing Git on Windows, Linux, or Mac
• Understanding jQuery Mobile’s Responsive Grid

You can see that all three of the ideas are related to the previous three, but are more specific. So these topics don’t offer the kitchen sink, so to speak (which is difficult to do well) but rather, they focus on a single aspect of the subject at hand, which will be much easier to present in an effective way and will, as a bonus, be much more likely to gain SEO value.

Conclusion

As already mentioned, I’m far from the perfect writer. But after blogging regularly for about 6 years now and editing 3-4 articles per week for over a year, I feel I’ve gained some insight into what readers like and what they don’t like, what works and what doesn’t work.

I hope some of what I’ve written here can help other writers trying to produce content that people in the industry will be interested in reading and sharing. There’s no single recipe for success, but I think the above tips can serve as a kind of general template for successful articles.