Rules to Better Blogging

Hold on a second! How would you like to view this content?
Just the title! A brief blurb! Gimme everything!

At SSW we encourage our employees to actively keep blogs about their achievements, discoveries, interests, and ideas. The biggest problem with putting up an article is that once it's up there it's there for the world to see. Do you express yourself properly in blog posts?

This set of rules aims to help you efficiently write clear, effective blogging articles. In some cases you might be interested in seeing our Rules to Better Technical Documentation for comments on how best to express your technical problems.

  1. Are you still UI aware?

    A blog is still a website that you want people to visit, so it’s important to consider the UI.

    ​Have a look at Jakob Nielsen's advice on the Top Ten Design Mistakes for advice on how you can improve your blog UI.

    Read more about Are you still UI aware?
  2. Do you have a 'subscribe' button on your blog? (aka RSS)

    The RSS or 'subscribe' button is a place on your blog that alow visitors to easily receive your blog's updates.

    Blogs that have a visible 'subscribe' button will certainly receive more returning visitors.

    Tip: For Wordpress, there are plugins that make it easy to insert the 'subscribe' button in your WP blog. We recommend:

  3. Do you know how to document what you are doing?

    If you are recording a choice you should create a rule, if you are explaining how you did something, it should be a blog post.

    If you are writing a really long email, ask yourself if it would be better as a lining blog post rather than a one off email.

    Also see: Do you know to make what you can public?

    image
    Figure: This rule describes the choice that was made
    image
    Figure: This blog post documents the task or thought process

    Hint: If you are really good you will end up with one or more rules, a blog post and a link in your email

  4. Do you know how to invite replies?

    Wither you are converting an email to a blog post or writing it from scratch, always invite and instruct discussion.

     SNAGHTMLf1a9ab
    Figure: Bad example, there are no instructions here

    SNAGHTMLef6f69
    Figure: Good example – Asking some questions at the end will solicit more feedback

    Although people may not comply, it helps them adjust from the world of email only.

  5. Do you know that 'Factual Content is King'?

    It is easy to think that "Content is King"; it is a well-known quote from an article by Bill Gates in 1996.  But incorrect content is not  very useful, so we think that "factual content is king".

    You should always:

    • Fix up your mistakes, and
    • Strike through content that is now been superseded, and add a comment. E.g. "This is now not an issue as it was fixed up in TFS SP1"
  6. Do you know to acknowledge people who feedback?

    If someone gives you feedback and you think it is worth incorporating into the content, you should always name them at the top of your blog post. This makes them feel good and gives your post more credibility.

    SNAGHTML1d4b746 
    Figure: Bad example, a static blog post. Does not look like it has been updated.

     

    SNAGHTML1d398ce
    Figure: Good example, dated and attributed updates give your posts credibility and make them seam alive.

    Make sure that the follow up and aggregate Twitter and Facebook users as well. Make all your readers feel included and you will create loyalty within your readership.

  7. Do you know to allow employees to post to their personal blog?

    Technical people need a little bit of a free leash in order to be creative. This will benefit the company they work for by demonstrating how technical your staff are, by driving more traffic to your site, and making your staff happier.

     Figure: Bad example, employees must post to the corporate blog.

    Figure: Good example, Allowing employees to post to their personal blog is a win, win situation. But they should do the Gold Plating after hours
    See: Do you know to do the gold plating after hours?

    Tip: Get your employees to add an “SSW” category to their blog so you can aggregate their posts onto the corporate site.

  8. Do you know to do the gold plating after hours?

    There is always the need to Gold Plate a blog post. And this is good. But if you are posting to your blog during work hours you should avoid this. You can always open it up after hours to add this.

  9. Do you know to make what you can make public?

    ​​As long as there is nothing confidential or NDA in the content, any discussion point should be made public. Transparency is the name of the game. The more transparency you have between customers, management, and your technical employees the better. This fosters trust and a closer working relationship.​​
    image
    Figure: Bad example - This is just an email and is hidden from all those outside of the recipients. Any answer here would only be of use to those on the list. What if someone new to the company had the issue​ or someone outside of the company?
    image
    Figure: Good example - writing a blog shows both how you deal with mistakes encourages the wider community to contribute with the discussion

    So keep jewels from being left in your inbox. Remember that you are inviting replies​, and that the gold in this process.

    Note: If the discussion is not worth a blog post, then tweet it and link to the rule.

  10. Do you know to tip, don’t rant

    Probably the best reason to blog is when you have made a mistake, especially if you were pulled up for it by a peer. Post about the mistake you made, why you made it and how you are going to try and avoided it in the future.

    Turn a rant into a tip…

    SNAGHTML1b864a4
    Figure: Bad example – It is too easy to rant

    SNAGHTML1b94284Figure: Good example – What started out as a rant about Plaxo became a tip on how to get round it

  11. Do you know to update a blog?

    Use the word ‘updated’ in capitals and in red. The date should follow.

    E.g.  

    UPDATED: 1 August 2010 [what you did]”

    image   

    Figure: OK example – Although Peter has the right idea, he needs to think more of a global audience
    http://blog.gfader.com/2010/06/avoid-boolean-parameters-in-method.html

     

    image   

    Figure: Good example – its easy to see when the updates occurred
    http://blog.hinshelwood.com/archive/2010/02/10/upgrading-from-tfs-2010-beta-2-to-tfs-2010-rc.aspx

     

    image   

    Figure: Ultimate example – Mike has gotten into the swing of things
    http://mikefourie.wordpress.com/2010/07/02/windows-live-essentials-wave-4-betalive-sync/

    You should also apply this technique to youtube videos you record.​​ 

    UpdatedYoutubeTitle.png

    Figure: Good Example - Following up on bug video makes it clear that the bug was fixed quickly.



  12. Do you post all useful internal emails to the Company Blog

    Most companies have intelligent people who make some relevant and useful points for the greater community or industry, while writing internal emails. Those emails should be published to the company blog for the following reasons:
    1. It provides great content for Google to index
    2. It raises the profile of your company around the topics discussed
    3. It shows the industry that you have intelligent and forward thinking staff
  13. Do you clearly highlight video posts?

    We all know the feeling after a long day... Exhausted, we wander the internet, lazily looking for content to consume easily. For many, this normally takes the form of watching videos after trailing through their Reddit, Twitter, & other social media platforms. Therefore, it is important to make sure that your blog post titles stand out to this demographic.

    One simple way to do this is to make sure that the first word of your blog post is "VIDEO – ". 

    Stevo-Bad-blog.png
    Bad example: Great content, but from the title you would be unable to tell that this is a video 
    Chris-Good-blog.png
    Good example: Easy to see from the title that this includes a video
  14. Do you know how to share a touch of code?

    ​Any regular blogger who writes about code knows that embedding code snippets into their posts can be a real pain! ​

    Syntax highlighting, special tags and keeping a track of your code snippets can be a nightmare. As a developer, you're sold on the virtues of source control, making changes then rolling back, forking, and cloning code. Wouldn't it be great if there were a simple way to share a touch of code?
    2014-03-08_19-49-571.png
    Figure - Using images for code snippets is difficult to maintain.

    Introducing Github Gists, which makes sharing, embedding and keeping track of code snippets easy. The standout feature of Github Gists is that every code snippet (often referred to by GitHub as a Gist) is behind the scenes a Git repository, which in turn gives you access to all of the benefits of source control.

    Upon editing an already published Gist, the previous versions are preserved. As to be expected with any good source control, you can use the built-in diff engine to highlight clearly the changes between any two versions of a single Gist. This sounds like it can get out of hand quickly, but you can easily view all your Gists by heading to https://gist.github.com/<username>/. 

    2015-12-03_15-46-34.png
    Figure - Easy to review your Gists.

    It is very simple to embed your code snippets using Github Gists, as you can embed any Gist in your blog with a single a line of JavaScript. The embedded Gists automatically display the current version of your snippet while still maintaining all the formatting and syntax highlighting. Furthermore, if you're using WordPress, it's even easier. Click here to find out all of the shortcuts for embedding Gists in WordPress! blogs. 

    2015-12-03_15-50-42.png
    Figure - Embeded Gist with JavaScript provided by Github

  15. Do you know why you should transcribe your videos?

    When you upload a video, what is the most important step for the videos future success or failure? 

    The most important step is setting the right title and description. As this is what search engines index to help others find your video content. For example, if we take the video below and make a list all of the keywords?

    transcribe.jpg
    Figure: How to improve the keywords of this video?

    We find that the video ​has the following keywords:

    • Windows 10
    • IoT 
    • Microsoft 
    • .NET
    • Micro Framework

    However it is missing important keywords such as:

    • open source
    • C#
    • GitHub
    • Universal Windows Platform
    • Raspberry Pi
    • I2C

    How do we capture all of these missing keywords?  You can't just overload your content with keywords, as your content will quickly become flagged as spam. 

    The answer is to have your video content transcribed. As it provides drastically benefits for the discoverability of your video content, while the organic nature of the written material ensures it is not flagged as spam. 

    transcription.jpg
    Figure: Checkout the rest of this example transcript - http://blog.chrisbriggsy.com/Ilija-Injac-on-IoT/

    A quick Google search will show a range of services which will make the task effortless. However, professional transcriptions are expensive. If you’re willing to spend a little time cleaning up technical jargon then it is worth checking out fiverr (https://www.fiverr.com/categories/writing-translation/transcription). 

    At SSW we have had success with this method as one of our devs, Chris Briggs transcribed all 3 hours of his SSW TV video content for under $90 USD and an hour and a half of his time to fix up jargon.