A small checklist of things before hitting that “publish” button! – A Gripe!

I read a short but well-written article by Nishant Gour which provided a good precis on the benefits of technical writing and posting. It was very good, and after commenting, I thought I would like to add a small personal addendum to the article.

I have noticed, here on Hashnode and elsewhere, there are far too many nonsensical, poorly written, grammatically incoherent, and erroneous articles, cut and paste regurgitated unstructured babble that serve no purpose other than some form of personal validation for the poster to state they have a blog. This helps no one except perhaps for content for the poster to use as an attempt at resume-boosting. Thus I would like to provide a suggested checklist for technical blog posters alike.

1. Research your market, is your posting relevant, useful for the community, or something new to bring, or is it merely something self-fulfilling?
2. Rants and raves (opinion posts) can be good if they are critically constructive, or simply humorous. I have posted in frustration and anger sometimes, it’s not been my best, but many people like a funny post, not many like a negative moan on developer blogs, again, keep it relevant!
3. Make sure you know what you are writing about! Don’t merely cut and paste things. I have seen many examples where text and code have been copied verbatim from other places. Explain a little what you are doing, at least to yourself in the planning phase. Also, there is nothing wrong with adding some explanations to your code.
4. Ensure your code is valid if you provide examples, test it, run it a few times. Ensure syntactically it is up to standard and correct. A sign of a poor article is mistakes in code, it usually means it’s been cut and pasted. If you have used it from elsewhere, remember to cite the source if it’s not originally your code, don’t leave it to responding to a comment someone has made about it. If it’s yours, check if you can clean it up or update it if it’s in context. JavaScript examples in particular often contain old code, poor practice, or just bad implementation. (remember, vars are a thing of the past 😜)
5. Don’t post nonsensical one-liners, blog placeholders, or minimal hello all posts. If you are posting for the first time, introduction posts are always good but make sure they are clearly written, contain sufficient information, and are more than a few words! If you have a post idea but nothing yet to say, don’t post a placeholder, this reeks of just wanting to get post counts up for the algorithms, it shows that you are not ready to post and are not interested in writing anything for others. I’ve seen plenty of blog posts with a title and nothing else, or a title and “post coming” comment, to me this is pointless and bad practice.
6. Check your structure, grammar, and language before publishing. I fully acknowledge and appreciate the language you write in may not be your first language, and that’s particularly impressive. However, setting aside the unimportant small errors, there are plenty of tools out there to check spelling and grammar, before you post, especially if you don’t initially write directly to the blog’s own editor (e.g. Grammarly). If you are writing markdown for example, StackEdit is a fantastic editor that also supports advanced markdown plugins like Mermaid or KaText, and it allows saving and synching to devices or cloud accounts.
7. Choose your title, I often change my blog titles regularly to try and get a feel for what would catch readers’ eyes, make it pop out during a browse of a feed. Make sure it actually makes sense both grammatically and contextually, if you are writing in a second language, remember some meanings may be different from your own language, and there can be confusion in a blog title from the content within. Also, a title should cleanly express what lies within, don’t deviate from a title in the actual content. If like I often do, find myself writing content that seems to deviate off-topic, I usually save that info for a new post later on.
8. Always check your work before posting, proofread it a few times, even suggest a family member, friend, or colleague read it, even if they may not understand the content, see if it reads well, and is at the least grammatically formed. As a former academic myself, I am continually reading over my posts, and checking the grammar and flow, I even have a bad habit of updating things after publishing!

Happy posting!