Tech Blogging at Mozilla

The following are some tips and tricks to allow us to get the best out of our blogging efforts. Not all of these will apply to you and not all of these apply to all the blogging we do, but for a technical audience we found them to be very effective.

Very, very basic things

When you start blogging for Mozilla, you become a spokesperson for us. As a spokesperson you will reach a lot more readers than you would on your personal blog (in most cases) and you have the benefit of the Mozilla community doing word-of-mouth advertising for you.

With that in mind there are a few very simple rules to follow:

• Be professional — no calling names, no racism, no sexism.
• Keep your political and religious views out of this — this is tech blogging.
• Have something to say — there is no point in repeating the technical info on the wiki when you don't add to it. Find the story around the technology, and blog about this. There will be a session on this at the speaker training.
• Speling duz kount — no matter how texting and tweeting is mangling language, your blog posts should not go down the same route. Do a spell-check on your posts. A simple mistake can very much discredit your posts. It is not rocket science, but gives a great first impression.

Do your homework

A good technical blog post should fill a gap. So before starting to write a new post do a search on the web and ask some people on Twitter and on lists and IRC if they know good resources on the topic you want to cover. You can use these as proofs of your own argumentation, learn something new you may have forgotten about and verify if your idea is really worthwhile posting the way you thought or if there is a new angle that other posts haven't played yet. Don't get discouraged if you find a lot of content - find out what is missing in all of them and write about that.

If you take content from other resources, makes sure you cite and tell the readers where you got it from. This means two things: you give credit where credit is due and you are not to blame if it turns out that later this assumption is wrong.

If your post is likely to touch on strategic project topics or is a hot topic that will be picked up by the press, make sure you flag it up with the Dev Engagement team - we can then rope in PR if needed to make sure there are no surprises.

Tone of voice

On Mozilla's tech blogs we are what Mozilla should be — the voice of reason in a mad tech world that has been taken over by marketing people years ago. We don't have shareholders pushing agendas down our throats, we have no quota to fill when it comes to blogging. If people tell you that, get them to contact the evangelism team and we'll take it from there.

Our publications should come out of interest, show what is in the pipeline and give people the information they need to get going, without prejudice towards other browsers and with a practical implementation as the goal. This does not mean we can't speak about Firefox only things — far from it, we should do that. It means, though, that we flag when something only works in Firefox and test if browsers can do the things we publish as examples. More on that in the "code examples" section.

Technical blogs are all about the information, not about sugar-coating it. We target experts and implementers, so we should not give them sales pitches. Marketing our products is the responsibility of the product marketing team and communicating our products the responsibility of the comms team, in their own respective language. So we should partner with those if posts are applicable to a wider audience, too.

With that in mind here are some tips on how to do write technical, engaging but not "sales-y":

• Make the reader the hero of the story — "Using the new full-screen API you can make any element in the document use up the whole screen - here's how to do that" is much more engaging than "The fullscreen API of the HTML5 specification allows developers to make any element take over the whole screen". The latter is interesting, the former gets the reader going.
• Use short sentences — nobody wants to draw a map to understand the structure of your explanations — this isn't Dostojevsky. If you have a long and complex sentence cut it up into two, both of which make sense.
• Skip the foreplay — keep tech articles snappy and interesting, start with what you will talk about, and immediately show the implementation. Follow up with the why and how and explain possible drawbacks as the last thing. Don't start with the history of the topic; it's rarely interesting or practical.
• Give a full disclosure — if something only works in a certain environment or Nightly, flag that up as soon as possible. We get far too many comments stating "doesn't work for me" — each of those undermines your technical credibility.
• Answer the WIIFM — "What's in it for me?" is a question every reader wants answered. So instead of just showing something for the sake of showing it, explain what it could be used for. "Firefox now supports context menus" is nice but "Create real applications with context menus in HTML5" is a better angle.
• Stick to one thing and explain it well — you are not writing book chapters, you are writing tech posts. Length is not a sign of quality — consistency is. So stick to explaining one thing well rather than throwing the whole kitchen sink at the readers. For more information, you have "read more" links or you could write a multi-part post.
• Give credit where credit is due — if your post is based on other work, or an update to older posts, link them. You'd want that to happen to you later on, too. Tell the world who the engineers involved with what you are talking about are. They deserve that.

Structuring your post

Structure is important when you want to write a good post. In tech, you are dealing with busy people. We want the facts and we want them in simple to take in chunks. This sounds terrible, but makes sense when you consider just how much information is out there on technology every single day. Thus, make sure to keep a good flow of your post by structuring them.

• Use proper headings — the h2 to h6 elements are powerful (h1 is normally already taken by the title of the post) as they give the eye something to rest, show the reader that they won't be overwhelmed with a long piece of text and they even aid accessibility. Users of screen readers can skip from heading to heading instead of having to listen to all you wrote. Search engines also love headings so make sure you use headings that make sense out of context.
• Tell your story — but not like you'd do in a presentation. Start with the climax (what you want to show), follow with the explanation of how it works, continue with where it might fail and what to do about that and end with "and one more thing" (other resources).
• Use lists — bullet-point lists, whilst horrible in presentations, make a lot of sense to make a lot of information easier to digest in posts. As you can see here another extra would be to have a bold first statement followed by a dash to give your item even more structure. Do not use numbered lists unless the order of the list items matters.
• Give away everything at the beginning — start with what you will talk about and then show how it works. This could be a linked example, a screencast, a screenshot — anything to get people going. Link to the source so people can download for later use whilst reading. Avoid the "Where do I get this?" comments. This is similar to the "What, where when" of news journalism that every first sentence of an article should answer.
• Add breathing space — each paragraph should deal with one topic. Nothing is more annoying than a massive blob of text. Give some breathing space for the brain to digest what you just described and what will come next.
• Extra value goes to the end — after your main post, it is always a good plan to add some extra value. End with a question, offer "read more" links, or show where the tech you talk about is used. Leave with an extra to keep people interested in learning more.

Linking

Links are an incredibly important part of the web. You could say they are the web. As such, it is very important in blogging to use them correctly. This is not rocket science but you see it done badly all over the web. Here are some tips:

• Link with meaningful text — this should be obvious, right? "Firefox now supports the The HTML5 menu item" beats "Firefox now supports the HTML5 menu item (click here for more info)" not only in terms of length, but also brings much more meaning to the link. Users of screenreaders often read just the links on a page, but "click here" means nothing out of context. Furthermore, adding the keywords in the link is good for search engines, so everybody wins.
• Links are proof, not context — external links are there to give your argument more weight. Think of wikipedia's citation rules. Do not expect the reader to follow any link you add to understand your post. Instead, explain and link to the external resource for proof. If a source contains information crucial to your post, quote it rather than just linking to it.
• Know your link targets — to be safe, when it comes to technical information, link to Mozilla sources (such as MDN or the Mozilla wiki). If you link to a third party page, you can not control if it will be there in the future. Of course if the third party info is the best, link to it, but be wary of what and where it is. By linking to a resource, you give it credibility — make sure it is worth it. A bad link promoted by you tarnishes your reputation.
• Test your links — broken links are broken promises. Also check your targets; there's no point in sending users to the top of the page when you want a quote in the middle of it.
• Provide "read more" resources — at the end of the article, list a few things that can give more information about the theme of your post. This allows you to promote the wiki or other resources, and also invites readers to learn what other people have to say about the topic. You are not only the expert writing this post but it also shows that you did your homework.

Images

In traditional blogging people will always tell you there needs to be an image in your post to catch people's attention. That works in tech blogging, too, but is not a must-have. That said, images are very powerful when you want to show something that might not be possible in the browser people use to read your blog. It is a great for "this is what it should look like". For using images there are a few tips:

• Link to the resource — if you use the in-built WordPress image uploader, the image will be linked to the full-size version of the image. If that is what you want, fine. However it makes more sense to link a screenshot to the real resource on the web — people click those much more than text links. Make sure your original images are crisp and big enough to avoid having to link to a "full size" version.
• Use absolute image paths — your image src should always be a full http URL. The reason is that RSS readers will then display them.
• Have a sensible alternative text — this is good for search engines and for accessibility. If the image could not be loaded for any reason, you'd still provide the information. Notice that alt="" is not at all the same as title="". It is tempting to give a good title attribute to an image as that is what people see when they hover the image. However, the alternative content is where your texting skills should go. Titles are nice-to-haves but in most cases not needed at all.
• Crop what is not needed — there is no point in posting full-screen 1440 pixel images when all you want to show is a form element. Crop your images down to the most needed part. You want the image to illustrate your point, not make people have to find things.
• Play nice with people's bandwidth — people will read our blog on slower or capped connections (in other words, mobile), so make sure to optimise the images to the lowest file size possible without making them blurry.

Multimedia (Screencasts, Audio)

When an image is not enough, the output is aural, or you want to show interaction, then you'll need to provide the reader with multimedia. You can follow a few simple tips to avoid confusion.

• Provide a fallback link — a lot of RSS readers filter out multimedia content. If you talk about a video in your post that is not visible, this will confuse people. Therefore it makes sense to add a sentence before embedding the video that links to the resource on the web. Like "Check out this example in action" with "this example" being linked to the YouTube video you embed following the sentence. That way, it makes sense for those who can see the video (and open/bookmark the video for later using the link) and those who haven't got video. The same applies to using an HTML5 video element. As the last fallback, inside the element provide a link to the video, telling the user the format and size, for example "Video recording of Chris talking on HTML5 at MDN hack day in NYC - 23MB - MP4".
• Keep them snappy — if you just want to show a quick demo, have just that demo without any voice-over. This is to show what things look like, not to replace the post.
• Cross-link from the video site — if you use YouTube to host your video, give the video a good title and description there and make sure to link to your post. A lot of traffic can come from there as people are very likely to share the video on Facebook, Twitter and Google+ and they might forget to link the original post.

There is more information on creating screencasts available here in the Evangelism Reps program.

Code examples

Let's talk about the thing that really makes a blog post a technical blog post: code examples. For detailed information about code examples and why they should be the best code you ever write you can check the Developer Evangelism Handbook entry on code examples, but here are a few very important points:

• Link the original source — preferably on GitHub, also a working example or at least as a zip. People should never have to copy and paste code to make it work.
• Embed readable code — there are a few options:
  • Use colour coding — the Hacks blog allows you to do that by adding <pre lang="$lang"> around your code where $lang can be xml (for HTML), javascript or css (and a few others).
  • Embed a Gist from GitHub — this has the benefit of your code being editable if needed. However, in most cases, a change in code would also have to be reflected in the text.
  • Embed an interactive code example — using JSFiddle, JSBin.com, Tinker.io, Dabblet or others. This is very cool, as people can play with the code, but you are also dependent on these services to be up and running. The iframe embedding also doesn't work on RSS readers, so make sure to link the URL and do the embedding, much like you do with multimedia. Be aware that posting an iframe in WordPress typically requires administrator privileges.
• Make your code work — as explained in the Evangelism handbook, your code must work. Write very paranoid and defensive code as your example. It is very tempting to show the shortest code possible, but we want to teach people good code, not how to cut corners.
• Write code for the web — our code examples should be code that works regardless of the reader's browser. This is not always possible, but when it is make sure to always check for the support of technology before applying it. When it comes to browser-specific code, also include vendor prefixes of other browsers and a prefix-less fallback. If a Chrome user sees an effect created with our code, he is a happy reader and will promote our post. We should never force people to use what we prefer as our environment. This is what bad marketing sites do — we are not that.

Cross-posting and promotion

This is a big thing and also involves other departments of Mozilla or partnering with other blogs, but there are a few simple rules to get things going:

• Do not publish the same blog post on different blogs — duplicate content is penalized in search engine rankings. The reason is that a lot of spam blogs happily copy good blog content to attract clicks. So if you have the verbatim post in two places, you are shooting yourself in the foot — or you are asking to be treated like a spammer.
• Write targeted smaller posts linking to the main one — for example a design blog could get a different screencast/image and explanation what a certain technology means for designers and then link to the original post for "detailed technical info".
• Link all the resources back to the blog — add the link in the description of the screencast video, the github repository and link it in the footer of the demo pages. Each part of your post can have its own distribution history on the social web, so linking them back means you keep them in context.
• Find outlets to promote the post — tweet about the post, maybe post on Hackernews and Reddit. Find expert groups in Facebook and Circles in Google+ to promote the post there. Also think about mailing lists, IRC channels and newsgroups. Play nicely though — don't just flood the web with your link, but find a reason why people in these groups would benefit from reading your post, and explain that reason along with posting your link.