Writing good Linaro blog posts

Here are tips for creating attractive, useful and easy to find technical articles with the Linaro blog.

Writing technical articles helps to share information about our achievements and our future plans. This should help users to use our deliverables and incite more developers to contribute to our projects.

The Linaro blog is running WordPress, today's most popular Open-Source blog engine.

If you already have your own blog, it may be a good idea to go on writing on it. People interested in Linaro can still get notified for your blog posts if you add your blog to Planet Linaro. This is also a way for Linaro to reach other reader communities.

Getting an account on the Linaro blog

User accounts on the Linaro blog are restricted to Linaro employees and member assignees. Therefore, the registration process is not publicly described.

To get an account, contact Jennifer Castelino:

  • <jennifer.castelino AT linaro DOT org>

After your account is created, you should update your profile by going to the login page and then to your profile page to make sure that all your details are filled in:

  • First name

  • Last name

  • Display name publicly as: this should be <Firstname> <Lastname> for consistency with other users

  • Biographical info: this section is rather important as it is used to describe yourself at the end of blog posts. Without it, blog readers do not know who you are.

You should also set your avatar. This way, a small picture of you is displayed in your posts and comments. This is much better than just displaying an anonymous "Mystery Man" silhouette!

To have an avatar on WordPress, you need to get a Globally Recognized Avatar (Gravatar), and associate it to the e-mail address registered in your WordPress user profile. Register your Gravatar from http://gravatar.com/. WordPress and other blog engines then automatically fetch your picture from http://gravatar.com/. This means that your avatar automatically works on several blogs you contribute to, either as an author or as a reader posting comments.

Writing blog posts

Authoring is very easy with WordPress. Posts can either be created with an easy to use WYSIWYG editor, or with plain HTML code, according to your own preferences.

Creating a new post

After logging in (shortcut), you can create a new post by clicking on Posts -> Add New (shortcut).

Suitable content

Before you go on and write your post, you should make sure that your content is suitable for posting on a blog. Readers usually expect technical articles that cover a topic with enough details and a proper introduction. Here are a few examples of good technical articles written by Linaro members:

On the other hand, here are other types of technical content that don't really fit in a blog, such as:

  • Very quick announcements, just a few lines long.
  • Weekly progress reports, with very little text to explain what each work item was about.

Keep in mind that blogs are often read by people who are new to a topic. If we go to raw details without any introduction, news readers won't be incited to read more posts from us in the future.

For such announcements, other media are probably more appropriate. A typical way is to post a message to the linaro-announce or linaro-dev mailing list, and publicize it on Linaro's Twitter account, through a hyperlink to the post in the mailing list archives.

Another great way is to advertise quick news on Linaro's Google+ page

Don't copy/paste content

Don't copy/paste content from other sources, at least without any further editing.

If you copy some text like the announcement of a release, please turn all text styles into proper HTML markup, such as:

  • Replace '*' by the corresponding HTML tags (<ul><li>...</li><li>...</li></ul>). Real bullets will look much better and will give consistency with the rest of the website.

  • Remove all the lines of a paragraph into a single line with no line feeds. Otherwise, WordPress will treat each line as a separate paragraph, showing a pretty ugly result.

  • Replace underlined text with the corresponding heading (<h2> or <h3>) tags (<h1> should be avoided, as it could look bigger than the post title itself).

Don't copy HTML code produced by a automated tool like LibreOffice or even worse, MS Office. Such code usually mixes markup and style, and the hardcoded style is likely to conflict with the default site style.

HTML code that you write should only contain content (and structure), but never style. Good web design practices recommend to keep style and content separate. Hardcoding style in blog post would cause issues if we want to update the Linaro blog style (CSS) one day, and would require a lot of manual work to keep a decent visual for all pages.

Check spelling

Posts with spelling mistakes look unprofessional and these mistakes can distract the readers away from the carried message.

Spelling mistakes are very easy to avoid. If you create your posts with a browser like Firefox, spelling mistakes should be underlined in red as in any word processor.

Add graphics

It's also good practice to add pictures and graphs to make your posts more pleasant to read and easier to understand.

To get started with pictures in WordPress, the easiest way is to switch to the WYSIWYG interface to add your images. Then you can go back to the HTML editor (if you prefer) to add more text.

Of course, you can also use standard <img> HTML tags to refer to images on external websites, or on your own Linaro home page.

Add meta information

To make your post easier to find on your blog or in search results, it is important to fill in extra fields about your post.

WordPress tag selector

Tags

Tags are used by WordPress to show all articles covering a given topic. They could also be used by search engines, so each post should be associated to suitable tags.

Tags are very easy to add with WordPress:

Make sure that you select all the appropriate tags.

Categories

Categories and similar to tags, but are usually broader and less specific than tags. Hence, there should be less categories than tags.

WordPress Category selector

As categories are also used by WordPress (at least in the style that we currently use), each post should also be categorized properly.

SEO title and description

SEO stands for Search Engine Optimization. SEO impacts the way your posts are presented in search engine results, as well as the rank amongst search results.

The most important field that you really should fill is the Description one. This is a quick summary that Search engines will display after the title and URL. Here is a typical example where the description was not filled:

Sample Google search result

Here, Google had to guess which excerpt of your blog post to use as a summary for the blog post. I'm sure that the author would have chosen another summary.

Keep in mind that search engine readers will often use this description to decide which links to follow. With a bad description, you could have many less readers.

Our WordPress installation also allows to set a title and keywords. You can safely copy the post title and reuse the post tags here:

WordPress SEO field editor

Another good advise to get better ranking in search results is to make sure that the post title contains the most important keywords that search engine users could look for. At least, Google is currently said to pay attention to this. This could change in the future, though.

Publish your post

Once you are all set, you can publish a post by pressing the Publish button. You may also put your post in Pending review state to let your colleagues review it before you publish it.

Comments

WordPress will send you e-mail to let you know when a comment is posted about your article. Don't hesitate to reply to these comments when needed.

You can also post your own comments, for example to give additional resources later, or to give updates a few weeks or months after the article was posted.

Announce your post

Once your article is published, you should let other people know about it:

  • Your post will automatically appear on Planet Linaro

  • You can announce your article on Twitter (can be from your own account)

  • You can announce your article on Google+

  • ... and on other social media sites. If your article is expected to reach a wide audience, you may also submit it to LWN.net, which is the most popular source of technical news in the whole community.

Other tips

If you typed your HTML code by yourself, we advise to check that your HTML code is compliant to W3C standards. This is very useful to spot obvious mistakes. This is also very useful to guarantee that your page will display correctly in all browsers. Respecting W3C standards is also important for accessibility, allowing people with visual disabilities to read your content with special tools.


CategoryHowTo

Resources/HowTo/Blog (last modified 2015-01-07 20:43:39)