My blog checklist
Recently I drafted my first blog for the Microsoft365PnPBlog on the Tech community. It explains on how to run reports on your tenant using the CLI for Microsoft and Azure Container Instances. After finishing the post Luise Freese reviewed it and we started discussing on how to write proper technical posts, and what should be part of it and what shouldn’t. With that short discussion in mind, I decided to write up ‘my’ checklist of things that I check before publishing.
Writing as a non-native speaker
The hardest part of writing in English as a nonnative speaker is that a lot the learnings you get at high school are all about ‘formal’ text writing. Most of my blogs are not formal, and I feel that it would not fit my goal or audience to so. The result is that I end up using a bit too many phrases that contain remarks like just click or simply do the following. Now I might not always pick them up when rereading my content, but I sure try. My blog check lists consists of three different topics:
- The blog contents, or textual styles.
- The metadata
- The layout and overall setup
Blog contents
I use word as my editor of choice and enabled the editor plugin. I made sure to enable the different inclusiveness checks you can. Keep in mind to check if there are new checks every so often. I see new options coming in every few weeks.
When writing blogs everyone has an opinion on how long it should be. I ended up sticking to the 300-word rule, and every blog should be 300 words. If I cannot make it 300 words, it should be a LinkedIn Post or Tweet.
Adding URL’s can help you supply background information. For Microsoft content it usually contains localized content, so I make sure that any URL to that content does not contain /en-us/ or /nl-nl/ in the URL. This ensures you get localized content for your profile instead of being forced by me by whatever I would put in the URL.
So, I end up with 4 things to check about my content.
- Use word and enable the editor plugin.
- Reread the blog and scan for words like simply.
- Remove language specific links to Microsoft content
- Make sure to have at least 300 words.
Blog metadata
Any blog should have some metadata. I run my blog on Hugo and implemented some speed improvements. That does mean I need to put in some metadata. It might differ for your blogs but I guess any blog has at least some metadata:
- There should be a publish date (my blog setup does not allow me to set a date in the future).
- I need to make sure I have a header image. Blogs without header images are ignored by Hugo in my setup.
- The infrastructure requires me to have at least a single category.
- There needs to be a slug in place. I try to make sure the slug has three to five words.
Blog layout
Any blog should have some sub headers for readability but as I write in markdown, I need to check them after pasting my contents from word. At some point I hope there will be a possibility to save to markdown from word. But for the time being I check them manual. I also make sure that all images have an alt text as this improves the accessibility for people who are using a screen reader. And finally, when code snippets are involved, I re-try or recompile them before publishing. This is to make sure I did not change parameter names and screw up the sample. Whenever i find a non-working sample on a blog I get annoyed right away, so I better fix that on my blog where I have control.
- Check sub headers
- Check images for alt texts
- Do code snippets compile
VSCode plugins
As I am using VSCode to publish and finalize my blog I use the following plugins to help me:
If you have any tips on my blogs, or you find code snippets not working make sure to let me know!