Confirmed users
376
edits
Evangelism Reps Training Program/TechBloggingAtMozilla: Difference between revisions
Evangelism Reps Training Program/TechBloggingAtMozilla (view source)
Revision as of 17:42, 9 April 2012
, 9 April 2012no edit summary
No edit summary |
No edit summary |
||
| Line 13: | Line 13: | ||
*'''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. | *'''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. | *'''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 worth while 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. | |||
==Tone of voice== | ==Tone of voice== | ||
| Line 36: | Line 40: | ||
*'''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 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). | *'''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 | *'''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 items 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. | *'''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. | *'''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. | ||
| Line 53: | Line 57: | ||
==Images== | ==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, | 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, 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. | *'''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. | ||
| Line 69: | Line 73: | ||
*'''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. | *'''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. | There is more information on [https://wiki.mozilla.org/Evangelism_Reps_Training_Program/How_to_prepare_a_screencast creating screencasts] available here in the Evangelism Reps program. | ||
==Code examples== | ==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 [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. | *'''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. | ||
| Line 81: | Line 85: | ||
**'''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. | **'''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. | *'''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. | ||
*'''Write code for the web''' - our code examples should be code that works regardless of your 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''' - as Google punishes duplicate content. The reason is that a lot of spam blogs happily copied 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 want 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 an 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 mailinglists, 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. | |||