CodeinWP CodeinWP

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.

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.

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.

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:

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.

56 Responses

  1. YourFriend says:

    That was a nice read. One thing I want to add is, “Always consider your readers as a newbie and don’t expect a lot from them” . In that way, you will write simple and easy to understand tutorial. This is what Google recommends to every blogger.

    • Good advice. I think there is a place for articles that speak to a more experienced audience, but that could also be improved by linking to good sources in the intro, especially if you’re going to assume a lot of knowledge from the start.

    • Ada says:

      “Always consider your readers as a newbie and don’t expect a lot from them”

      This is exactly what an editor I used to work with always said. This doesn’t mean your readers are dumb, but they are not supposed to be experts. For instance, a Web tech site might have readers with 10+ years of coding experience with one language but now they want to branch into another and in this aspect they are beginners. Or designers who want to learn some coding – they are not newbies to Web tech per se but coding is a brand new area for them. And since we don’t want to lose these readers, the option is to make the articles and tutorials user-friendly.

    • mar says:

      “Always consider your readers as a newbie and don’t expect a lot from them” agree this will attract new visitor and subscriber

  2. Nice read, with a lot of good info.

    As a side note, I’d not give the following example:

    For example, if you’re talking about Bootstrap’s Jumbotron component, link to it.

    but rather:

    For example, if you’re talking about Bootstrap’s Jumbotron component, link to it.

    As I think we should encourage people (by demonstrating good practice) to use link text that gives context to the user.

    • Done! :)

      You’re absolutely right. I often change link text in article submissions to encourage what you just said (i.e., to avoid sutff like “click here” and similar). Thanks!

  3. James Edwards says:

    The point you made about fear of “revealing their research secrets” is really interesting, and it’s something I learned the hard way in college. I used to avoid referencing external sources in essays, for exactly that reason — because I wanted to appear like I had unique insight. But it had just the opposite effect — instead of looking clever, it just looked like I hadn’t researched the subject properly!

    By extension, the same principle applies to “sounding authoritative” — it’s rarely the case that an idea can be presented as “this is the correct solution”, and if it is presented in those terms, it just comes across as arrogant and closed-minded. Much better to be conversational, to present ideas in terms of “this is what I think is best”.

    Even as I wrote that last paragraph, I wanted to say “dialectic” instead of “conversational”! And I must admit, I quite like old-fashioned phrases like “hence” and “whilst”, though avoiding them for the sake of internationalisation does make sense. Though I did use “former … latter” in my last SitePoint article :-P

    But I can’t agree with “avoid vague words” — they may not add anything to the article’s meaning, but they’re friendly and conversational, and they help an article to sound informal and to convey the author’s voice. Even something simple like “I really like this” sounds more enthused than “I like this”, and such phrases can help to express the author’s passion for, whatever it is.

    And why does everyone hate on opening braces on a new line? They add space — makes the code more readable :-)

    • Great points. And I really agree with your view on vague words (see what I did there?). The problem with many of the articles I’ve edited is that the authors are often using those vague words for no reason, and it amounts to nothing but filler, with no personality. I agree, use conversational terms, but it has to be delivered with some personality and personal experience.

      • James Edwards says:

        Absolutely. It can be a fine line between style and rambling — that’s what editors are for :-)

  4. One thing I forgot mentioning in my previous comment:

    Authors should do their research and make sure to always mention prior art – always.

    I recently read a very well written article that failed to do this—which I think diminishes the quality of that article.

  5. Ralph Mason says:

    You can copy and paste a real long dash (—), or you can use the character entity, &mdash;

    Em and en dashes are also really easy to type on a keyboard—something I do so often I don’t have to look at the keyboard.

    For em, it’s as follows:

    Mac: Shift Option -
    PC: Ctrl Alt - (‘minus’ key on your number pad)

    For en, it’s as follows:

    Mac: Option -
    PC: Ctrl -

    • I’m on a PC and those shortcuts don’t work on my keyboard. I’ve tried doing shortcuts for special characters before and I can’t get them to work.

      • Ralph Mason says:

        Darn, sorry about that. I’m on a Mac, so had to do some digging to find the keys for a PC a while back, and at the time they worked for me when I tested them on a friend’s PC. Will have to do some more digging.

      • Ralph Mason says:

        Came across this page—http://www.typewolf.com/cheatsheet—which is a handy guide to web punctuation. It says that alt + 0 1 5 1 is the way to type em on a PC keyboard, and alt + 0 1 5 0 for en.

    • James Edwards says:

      I generally find it’s better to use entities — because they still work on documents with non-UTF encoding.

      For ultimate interoperability, use numeric entities — because they don’t rely on the document understanding named entities (e.g. they work in any kind of XML).

      I can write ߞ in my sleep now :-)

      • My Chrome on Windows 7 won’t show the character you just put in there. I just see a square (See: http://i.gyazo.com/22feb372d065e51423fd489e9ece9af5.png). I know that happens often when people post special characters on Twitter (but they look fine in Firefox). And I’m pretty sure I’ve seen a few open bug reports on that. I have no idea why they haven’t fixed that bug yet.

      • Ralph Mason says:

        entities … still work on documents with non-UTF encoding

        It’s been quite a few years since I’ve come across a site or software tool that baulked at keyboard ems, ens, ellipses and so on, so I guess I’ve become complacent about that.

    • James Edwards says:

      Can’t make it produce a complete entity without parsing :-) I meant & #x2014;

    • Valentin Born says:

      Well, it’s certainly a bit off-topic, but the shortcuts likely depend on OS/GFX-system/keyboard layout—on my “PC” (running X on a linux-based system with a German keyboard layout) I input an ndash with “Alt Gr”+”-” and an mdash with “Alt Gr”+Shift+”-“—or with the more general Ctrl+Shift+U, 2014, Enter (2013 for ndash).

  6. Ralph Mason says:

    I should have added that they can also be typed on touch devices. I can only speak for iOS devices—where, if you hold your finger on the hyphen, a popup offers other similar characters, like en and em dashes.

  7. Well ritten, Louis. I is agreed with yoo!
    Peeple woodn’t belief how bad mi writings are. Yoov make my artikels mutch betta.

  8. Vikas Avnish says:

    breakdown structures with illustrations,interactive exercises

  9. fretburner says:

    > “AJAX” to “Ajax” (believe it or not, it’s not an acronym!)

    I’d always thought that AJAX stood for ‘Asynchronous JavaScript and XML’, which the Wikipedia page seems to confirm?

    • It does stand for those things, but it’s not an acronym. I know that sounds contradictory, but it’s true. (This is especially true because the “XML” part is optional for use).

      Ajax could have been called “Peanut Butter”, but it would still stand for “Asynchronous JavaScript and XML”. That’s why Jesse James Garrett didn’t write it in uppercase, even in the first article about it in 2005. He never meant it to be an acronym.

      You can kind of compare it to the word “PHP” in a way. “PHP” is kind of an acronym, but it’s really not. It just represents a technology.

  10. Tom says:

    Thank you fo sharing, it was a pleasure to read.

  11. Agree! these tips can remarkably make any website to stand outside the crew. Linking to great sources not only influences your credibility but also helps to get support from others.
    Excellent post & clean presentation..keep sharing..

  12. Ada says:

    A great article with lots of useful insights! Thanks!

    I’m one of these sinners who frequently use “powerful”, “useful”, or “easy”. To make it worse, with “powerful” and/or “useful” I generally do exactly the opposite to what the article suggests – I start with “powerful” and/or “useful” and in the very next sentence I explain what’s so “powerful” and/or “useful” about it. :) My reasoning is this – “powerful” and “useful” catch the users’ attention (they are like a hook) to read further. Now, when I have their attention, the explanation of the features should prove that “powerful” and/or “useful” are true. In a sense, if I don’t catch their attention with the buzz words, they might not bother to read the features at all.

    I try to use “easy” as an encouragement, but you are right, what’s easy for one person might be rocket science for somebody else.

    As for sourcing, I personally try not to be too generous with links mainly because of SEO/readability reasons. Outbound links in SEO can hurt, and when you have too many (internal) links in a text that require the user to open them, read the stuff the link points to, and then continue with the article, this is annoying, not to mention that the user might not come back at all.

    Links are tricky on many levels. I remember a couple of years ago, when I was writing for a tech news site, the shock and horror we went through, when we accidentally discovered that a link, or a couple of links, in a very old article (though still indexed by Google) was not pointing to the content we originally linked to — same domain, different content. The site we were linking to had transformed itself from a decent tech site into a porn site, or a crackers’ community, or a get rich quick scheme, I don’t remember exactly, and Google isn’t fascinated with such links. :)

    Of course, if you link to W3C sites, or php.net, this is unlikely to happen, but if you link to another tech blog, you never know what it might turn into in a couple of years. When you have tens of thousands of articles, checking manually all older articles for links that have gone bad is simply impossible.

    • Very nice points, Ada. Thanks!

      Just to clarify, in the article I said:

      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.

      So I think you’re doing fine. In all things, there’s balance needed. I just find too many authors go crazy saying how useful/easy/amazing something is, rather than just showing why those things are true.

      And yes, I’ve heard others mention the problem about SEO links going bad. I remember when Webdesigner Depot used to “nofollow” all external links for that very reason. I don’t think they do that anymore (too lazy to check!) but it can be a problem. But in a case like that, I don’t think it’s a permanent issue anyhow. You can do regular link checks and use Webmaster tools to disavow links, and those problems can be cleared up. And like you said, if you stick to good sources, you’ll probably never have that issue.

      Thanks again for your thoughts!

  13. Baldovinoroy says:

    Great!! thanks for the informative & helpful article and step by step guideline..I think interested person on this field will be more benefited.It is amazing to read.I am also working this sector.I noticed some new ideas also.I am totally agree with your post. Thanks again

  14. Web Dandy says:

    Excellent and very helpful article Louis. It’s great to see what people are looking for in an article or tutorial – and with specific examples! Sometimes its so hard to get articles accepted so these pointers are really appreciated. Thank you for sharing your insights.

  15. Nikhil says:

    Fantastic! Very informative & helpful article and the best thing is that anyone can easily understand what you want to say. Thanks.

  16. Wonderful article, great points and examples, time to review some articles!

  17. Hi Louis,

    I am blogging since one year, I used a lot of vague words in my articles, after reading this post I learned so many things about copywriting, like reference linking importance, meaningful intro and the long dash.

    Thanks for sharing your experience with us, I think these skills are very important to become a successful content writer, see you soon with another article.

  18. I remember a couple of years ago, when I was writing for a tech news site, the shock and horror we went through, when we accidentally discovered that a link, or a couple of links, in a very old article (though still indexed by Google) was not pointing to the content we originally linked to same domain, different content.

    • Chris says:

      A little off topic, but we find recording videos (Bandicam pro, a perfect tool) has been 1000 times more advancing to our staff members than long manuals. It’s amazing how much subtext is missed when your stuck to a written medium.

  19. ariannabates says:

    Terrific blog. Detailed and well written. I just come to your blog about web development updates.

  20. Shivang says:

    I Don’t know why my post don’t rank well in search engine after doing perfect seo. but one day i have shared my article on social media and suddenly i got first page rank. This is miracle

  21. Ravi says:

    How long does it take for a new blog to get rank well in search engine. I have written 50 post in the last 30 but only getting daily 500 traffic. Please help me

  22. sunny says:

    really very helpful post for developing a web, thanks a lot for sharing it with us
    cheers!!!!!

  23. Lewis says:

    Thanks Louis Lazaris for sharing an awesome tutorial, even great for beginners as well as for the professionals.

  24. Aditi says:

    Great tutorial for web developing thanks for share with us. It is very helpful for us.

  25. Shailen says:

    Thanks for sharing such an awesome article. We been in the web development industry for awhile and wanted to find a better way to write web development articles in an attractive ways to our followers. We have tried blogging via vandeyargroup.com/blog with some success but we will certainly implement what you have said and keep you updated on the results. :)

  26. John says:

    Wow incredible article this will help me a lot as a writer

    Thank you for sharing this article

  27. Devin says:

    It’s great to see what people are looking for in an article or tutorial – and with specific examples! Sometimes its so hard to get articles accepted so these pointers are really appreciated. Thank you for sharing your insights

  28. nice article, thanks to the author for sharing such a great content.

  29. jayant says:

    This is very useful. I have been doing so many mistakes in my writing. time for some corrections. Thanks for the heads up. easy to understand.

  30. Vikas Kumar says:

    Thanks for this useful information. I usually like to read great article that it can help me in writing superb articles & tutorials.

  31. Hey Louis,

    Great informative post on writing a web oriented article. Really liked your points for add links to support statement… Really useful post for beginner to content writing.

    Thanks for your useful post. Keep up the awesome work!

    -Rajinder

  32. Thanks for a long and detailed post about it. Great Article.

  33. Aditya Laces says:

    It’s very helpful tutorial for writing article.

  34. Jakki says:

    I’m SO glad I found your site because I’ve actually been reading your articles for the entire day- and learnt so much in the process. I use npm often but your article for beginners really helped with a few unanswered questions I had, which I think is common in the dev community these days. Things become popular and we use them, but grasping the concept of why is so much harder. Take for example Webpack, and it’s really limited documentation. In my opinion it really excludes a lot of developers who may not know the exact reason for it because it doesn’t bother to explain it self properly.

    I think you are a fantastic writer and you explain things in layman’s terms that are easy to understand, unlike a lot of other dev writers who assume you already know what they are talking about. It’s so refreshing and I think you are in fact one of the best dev writers I’ve come across that can explain what you mean without being too overly complicated. Keep up the awesome work!!!

  35. Steve Smith says:

    I have been doing so many mistakes in my writing. time for some corrections. Thanks for the heads up.

  36. Steve worth says:

    Thanks Louis Lazaris for sharing an awesome tutorial, even great for beginners as well as for the professionals.

  37. Akanksha Sen says:

    Such a comprehensive guide on writing web development tutorial. Thanks for sharing.

  38. Jessica says:

    Hey. Thanks for sharing this valuable information. This article is very helpful. Would love to read more from you. Keep up the good work.

Leave a Reply

Comment Rules: Please use a real name or alias. Keywords are not allowed in the "name" field and deep URLs are not allowed in the "Website" field. If you use keywords or deep URLs, your comment or URL will be removed. No foul language, please. Thank you for cooperating.

Markdown in use! Use `backticks` for inline code snippets and triple backticks at start and end for code blocks. You can also indent a code block four spaces. And no need to escape HTML, just type it correctly but make sure it's inside code delimeters (backticks or triple backticks).