How to Write Good Web Development Articles and Tips

busyI’ve been working as Web Developer since 2007, mostly editing HTML, CSS, and jQuery content. I’ve also helped out with some general Web stuff (Mysql, PhP, build tools, and other generic content).

I try write quick notes to help me remember how to do some things quicker without picking around in the web, and in some times also my personal thoughts and reflection each week.

Probably most of them not clear enough, but for me and for other most of them are like good reference sheet. I know many of my articles suffered from the same problems. So I put together my thoughts on, what makes a good web development article or tutorial:

Member to 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:  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 Article is about particular tool or technology (like a specific jQuery, Php code), 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 article is common in context (like just simply snippets of code), then is probably fine not including a link to library page.

Link to Documentation

Related to the point of linking to sources, if you’re talking about specific features in Bootstrap, or jQuery, or another tool or framework, you should link to the sections in their documentation that you’re discussing. Or in other case if it is own idea try to well commented and make clear example what you try show to other.

When you explain some code ideas tray avoid shorthanded code and always check if all this code have all dots, colons …

Also when I digging for some ideas sometimes I get the feeling that authors are afraid to link back to a resources  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.

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. For demos wit typical code always help you JSFiddle

Include a short but effective Introduction

Don’t Try to Sound Professional or Formal

Easiest is always best solution to approach everyone CSS and HTML have been around for years. The former for 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.

Headings Alone Should Develop the Theme

A reader should be able to read the title of your post, Keep each of the primary headings in order,  is not only help the reader but also will improve your SEO ranking

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 Alternate Between “we” and “you”

In a start, you might be talking the user. So you might say something like: We…

Later in the article you say: You…

And just after: I…

Have Consistent and Easy-to-Read Code Blocks

When including code blocks in articles and tutorials, I try to keep in mind few general rules:

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

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.

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. If you’re talking about one specific CSS feature, don’t include all the styles. 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. And always you can break the code block up, discussing it in steps.

Conclusion

I hope some of what I’ve written here can help other writers trying to produce content. I think the above tips can serve as a kind of general template for successful articles.

 

Leave a Reply

Your email address will not be published. Required fields are marked *