View source for 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.
*'''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 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 [http://www.whatwg.org/specs/web-apps/current-work/multipage/interactive-elements.html#context-menus The HTML5 menu item]" beats "Firefox now supports the HTML5 menu item ([http://www.whatwg.org/specs/web-apps/current-work/multipage/interactive-elements.html#context-menus 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.
*'''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.
*'''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, 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 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:

*'''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 wanted, 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 but 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 to explain with those, not make people have to find things.
*'''Play nice with people's bandwidth''' - people will read our blog on the go, 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 audial or you want to show interaction then you'll need to provide the reader with multimedia. You can follow a few simple tips there to avoid confusion.

*'''Provide a fallback link''' - a lot of RSS readers will 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 to link to the resource on the web. Like "Check out this example in action." with "this example" being liked 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 - like "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 [https://wiki.mozilla.org/Evangelism_Reps_Training_Program/How_to_prepare_a_screencast creating screencasts] available here.

==Code examples===

Last but not least 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 [http://developer-evangelism.com/code.php 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''' - our blog allows you to do that by adding &lt;pre lang="$lang"&gt; 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 reflect in the text.
**'''Embed an interactive code example''' - using [http://jsfiddle.net JSFiddle], [http://jsbin.com JSBin.com], [http://tinker.io Tinker.io], [http://dabblet.com/ 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.
*'''Make your code work''' - as explained on 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.