Secret ingredients to quality software


Rules to Better Blogging

21 Rules

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.

  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?

    Figure: This rule describes the choice that was made

    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 encourage blog comments?

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

    Figure: Bad example, there are no instructions here

    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 acknowledge people who give you 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.

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

    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.

    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?

    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…


    Figure: Bad example – It is too easy to rant


    Figure: 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" clearly (in capitals and in red for example). The date should also be added if relevant.


    UPDATED: 1 August 2010 [what you changed]

    RulesBloggingUpdate OKPeter
    Figure: OK example – Although Peter has the right idea, he needs to think more of a global audience - See live

    RulesBloggingUpdate UltimateMike
    Figure: Ultimate example – Mike has gotten into the swing of things - See live

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

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

    Related Rule

  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 add a prefix on blog posts titles?

    The prefix is used to give context to your blog posts (or other type of content), so users know what to expect.

    Example 1: Use " CODE:" when your blog post is about coding  or " VIDEO:" when it has a video.

    Northwind Traders with Entity Framework Core

    Figure: Bad example - Post title with no prefix

    CODE: Northwind Traders with Entity Framework Core

    Figure: Good example - Using a prefix in the post title

    Example 2: Use prefixes (based on the content) for grouping and a better scanning:

    Configure your SSW Email on your mobile (for Android users) Configure your SSW Email on your mobile (for iPhone users) Mobile Phone Answering Message Install the Control4 App on your phone (Sydney Only) Configure Skype for Business (Not for China office) Configure Skype Link your Azure & Azure DevOps (was VSTS) benefits to your SSW Organizational Account Request Access to VSTS Projects Do you know how to find stuff? Setup and Create a timesheet in TimePRO Setup your HR Records (Not for Work Experience) Your details on payroll system CRM - Add your details to CRM How to find an employee’s phone number? Make a small code change on (Developers only)

    Figure: Bad example - Data list with no prefixes

    Phone - Configure your SSW Email on your mobile (for Android users)  Phone - Configure your SSW Email on your mobile (for iPhone users)  Phone - Mobile Phone Answering Message  Phone - Install the Control4 App on your phone (Sydney Only)  PC - Configure Skype for Business (Not for China office)  PC - Configure Skype  DevOps - Link your Azure & Azure DevOps (was VSTS) benefits to your SSW Organizational Account  DevOps - Request Access to VSTS Projects  Intranet - Do you know how to find stuff?  TimePro - Setup and Create a timesheet in TimePRO  CRM - Setup your HR Records (Not for Work Experience)  CRM - Your details on payroll system CRM - Add your details to CRM  CRM - How to find an employee’s phone number?  Exercise - Make a small code change on (Developers only)

    Figure: Good example - Using a prefix in data

  14. 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
    Bad example: Great content, but from the title you would be unable to tell that this is a video

    Chris Good blog
    Good example: Easy to see from the title that this includes a video

  15. Do you avoid the term "emotional"?

    Bad example: to sound like you are emotional about this

    Good example: to sound like you are passionate about this

    Taken from the video "Chris Voss: "Never Split the Difference" | Talks at Google" at 23:50.

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

    2015 12 03 15 46 34
    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
    Figure - Embeded Gist with JavaScript provided by Github

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

    Figure: How to improve the keywords of this video?

    The keywords for the video above are:

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

    Figure: Checkout the rest of this example transcript -

    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 (

    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.

  18. Do you add a featured image to your blog post?

    A relevant featured image is a great way to add a splash of color to your blog and make your content visually appealing.

    blog no feat image
    Figure: Bad Example – the content might be interesting but it is not very appealing

    blog with feat image
    Figure: Good Example – the content is more appealing

  19. Do you know where to find images for your blog?

    You will need to ensure that you have the rights to use these featured images. A few options include:

    1. Purchasing a subscription to a stock image site
    2. Using a royalty-free stock image site. E.g. or
    3. Using Google Images that are labeled for reuse:

    google image labeled reuse
    Figure: Finding Images Labelled for Reuse within Google Images

    1. Taking your own photos

    Ensuring you are not breaching copyright will save you from any trouble in the future.

  20. Do you share every blog post?

    You should always publish your blog posts to all social media platforms you use. It helps boost traffic and visibility for your site.

    Don't simply share the URL and maybe the title, as it won't make people get interested in taking an action. On social media, nowadays, you have an average of 5 seconds to get someone's attention on the feed – sometimes even less than that. So, you should put the effort in carefully choosing a catchy image to make your blog post interesting visually on someone's feed and adapting the content to different social networks. For example, if you use Twitter, you will have fewer characters. A good starting point is to choose a statement or a statistic from your blog post to share on the social media post and give the user a snippet about the content they are about to read.

    The combination of a good image and an explanatory caption providing enough (and interesting) information from your content will make the user want to visit your blog to find out more about what you have to share.

  21. Do you use a signature with a link when commenting on a blog?

    Backlinks are a big part of Google's ranking algorithm, and one way to take advantage of that is to make sure that you always comment on people's blogs... this could be to ask a question, or just to say thanks, but make sure you add a link back to your company website after your name.

    Thank you, that worked for me Ulysses Maclaren 

    Figure: Good example - adding a signature with URL in your blog comment

    On the management side, you can see if your employees are doing this by googling (in this case) "Ulysses Maclaren" during annual reviews to see how much google juice they are adding to your website.

We open source. This page is on GitHub