Evangelism Reps Training Program/TechBloggingAtMozilla

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 propaganda for you.

With that in mind there are a few very simple things to keep in mind:

• 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.

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, we 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 that fact up 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 bore them with marketing talk. This can come later when we cross-link the posts from press releases or marketing blogs. With that in mind here are some tips on how to do that:

• Use active voice - "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 got a long and comples 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.
• 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 are undermining your technical credibility.
• Answer the WIIFM - "what is 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 - h2 - 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 put sentences in there that make sense out of context.
• 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 execution of the list item matters.
• Give away everything at the beginning - start with what you will talk about and 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. In news journalism this is the "What, where when" that every first sentence of a piece of news should answer.
• Add breathing space - each paragraph should deal with one topic. Nothing 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, 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 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. "Click here" doesn't make sense for someone who can't see. 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.
• Know your link targets - to be safe, when it comes to technical information, link to the wiki. If you link to a third party page you can not control if it will be there in the future. Of course if there is a better third party info link it, but be wary of what 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.
• 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 - it promotes literacy and gets people excited about learning more.
• Test your links - broken links are broken promises. Also check your targets - no point to send users to the top of the page when you want a quote in the middle of it.

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 need-to-have. That said, however 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 "this is what it should look like". For using images there are a few tips: