Contributing To A Blog

Writing content that other people will want to read is a skill that takes practice and is quite different to writing personal notes or technical documentation. This site is an internal playground to practice but that doesn’t mean that you should not strive to produce something that could be displayed externally. I have written a few guidelines that I think are important. However these are not all hard and fast rules and are only some pointer to get you started on the correct track. Don’t be scared to try even if you think you have breached some of the below rules. I am pretty sure this very post breaks some of them (and I will leave it up to you to tell me how I could improve it).

NB: This post was written for an internal blog that was a stepping stone for team members who haven’t written external blog posts to practice on. I have copied it here as the advice is still good but obviously if you are a solo developer some of the recommendations might be hard to follow.

1. Is this a story that needs to be told?

Before you start writing something, ask yourself is this something I would want to read? If the answer is No, why would you expect other people to want to read what you have written? Even if you think they need to know about it, writing something that you are not passionate about is extremely difficult and without a captive audience best avoided in this situation. Then flip the question around and ask is this likely to be something other people want to read?

Next, ask yourself have I read about this somewhere else? This time the options are less obvious. If the answer is No, check the answer from the above question is still definitely a Yes. It maybe you have a brand new topic that no-one has ever written about in which case that is ideal. It maybe that other people have written about it but only as far as user guides or other technical documentation. But do a quick google to check. If the answer is Yes, ask yourself are you bringing something new? Are you just agreeing with someone else or repeating what someone else has written. If you are, stop, re-inventing the wheel is not progress. If you are disagreeing or putting your own spin on something then great (but be careful that your disagreement is written kindly in a constructive way). The other option here is that there is huge volumes of information on the internet and you are creating a summarised and curated list of that information as one of those doesn’t exist, that would also be OK.

2. Check your facts and provide references

If you have facts or quotes provide references that back them up or a repeatable way to reproduce the results (code repository maybe?). If you are stating an opinion, state why you hold it and what facts that lead you to that opinion. Remember, this site is to practice publishing stuff that could then be published externally where nobody will know that you are technically exceptional. The reader may not know you and hence will not be aware of your technical background, as such they will not just believe you because you say so. But if you provide links or ways to back up the factual statements you are making, people are more likely to listen to your opinions or summaries.

Further to this, try and make sure your idea is based on a logical progression of ideas and then make sure your story leads the reader through this progression. This means when they reach the point where you state your conclusion they understand why you have made your hypothesis or why your opinion is such. Also, remember to play devils advocate and think about what could be counters to your opinion and try and explain why your idea is still valid.

3. Remember the value you want to deliver to your readers

The value should be the conclusion to your story, but always keep this in mind when writing. You are taking your reader on a journey, a clear defined target or goal to reach on the journey means people are more willing to keep reading. If you can see the summat of the hill you are climbing it is much nicer journey that one through a dark forest with no idea of what you are trying to reach.

4. Check your formatting, spelling, tags and images

Precise tags allow readers to find your article and know that they might be interested in it. Good formatting and nice image will make the article inviting. Many blogs recommend using one of the free creative commons image libraries such as Unsplash which is fine, just make sure you give credit where credit is due and make sure you don’t use the RAW full size image.

Get someone to check spelling and grammar. If your reader starts reading but notices lots of mistakes they will be put off. At best they will question your attention to detail and if you have actually missed something, at worst they will be put off so much they will simply stop reading.

5. Check your past work

Finally, check you previous work. Have people made comments on things you have written before suggesting how you could have done better? If so, have you considered their advice and is this piece of work better than before. As I mentioned at the start, this blog exists to help you improve. The above are general guidelines to help you do just that but practice and peer review is the best way to actually improve. Make sure you take advantage of any constructive criticism and make each time you write it becomes better and better!

Cover image from Unsplash

• Contributing