Structuring a Blog Post

A blog post on a subject such as programming is likely to me more complex than just a set of paragraphs with images. For that reason I feel it is important to establish a structure for your posts which you can build each one around.

Of course it doesn't have to be fixed - you can adapt the structure to each post - but it does make it easier to create a well organised post without starting from scratch each time.

I write all my posts in raw HTML (yes, really) and have a template HTML file which I copy and fill in. Everyone is going to have different ideas and requirements onwhat the template should look like so I will just list some of the items mine contains to give you a flavour of the sort of things you might want to include in yours.

  • A banner graphic. Not strictly essential but highly desirable for aesthetic purposes.

  • A brief introduction to the topic and description of what the post covers. For example you might state that you will be writing about reasing PostgreSQL data using Python, and including code snippets which readers can adapt for their own use.

  • A detailed discussion of the topic, including sub-headings and code snippets where necessary.

  • Details of any external libraries, frameworks etc. used in your code. Include details of how to download and install them or links to the official documentation.

  • If you are including source code for a full runable solution include at least the main parts of the source code. You may want to break this up into easily digestable chunks.

  • Discussion of the source code.

  • Links to code download and/or Github repository.

  • Diagrams and other descriptive graphics, inserted at the relevant position.

  • You might want to include two or three images or photographs for aesthetic purposes to break up a daunting wall of txt and source code. Make sure they are relevant though. A puppy or a sunset might look nice but will also look absurd in a programming blog unless you are writing about software for veterinary surgeons or calculating sunset times from astronomical data.

  • Internal and external links to other relevant posts. Insert them within in their natural position in the post with anchor text that flows as part of the sentence.

Please let me know in the comments if you have any other ideas about what should be included in programming blog posts.

Leave a Reply

Your email address will not be published. Required fields are marked *