How to elevate the quality of your blog articles

[Travis Toulson]

Blogging is more than just putting words on a page. There is an art to creating a well written article. Done well, an article can influence, educate, entertain, or inspire others. Fortunately, this is a skill that can be learned. This guide will help you on your path to creating high-quality articles that make a lasting impact.

Craft a compelling title

Your title plays a number of critical roles in the success of your article. Most obviously, it is the first impression readers have of your article. It can determine whether readers click through the social media link or search result to read your article in the first place. Additionally, the title plays an important role in Search Engine Optimization (SEO), affecting what searches will lead to your article. Lastly, it sets the reader's expectations for the contents of the article. To craft a compelling title, you want to make sure the title is:

• Clear: Avoid cryptic or overly clever titles. The title should be easy to comprehend.
• Descriptive: The title should match the content of the article
• Intriguing: Your title should communicate why the reader should read the article. In many cases, this can be as simple as illustrating the problem the article solves.

With those criteria, let's look at a few examples:

Good Examples

• How to do full text search with GlideRecord - Simple, concise, and perfectly describes the contents. "How to <something>" is a very useful structure for meaningful titles. It shows that you don't need to be clever to be intriguing.
• Setting up and testing your first GraphQL API Tutorial - Once again, this title is clear, descriptive, and clearly articulates its value to the reader. Titles and articles that address "first" experiences or "getting started" are typically appealing to a wide audience, because we all have to start somewhere!
• AI-Powered ATF Testing: How Now Assist for Test Creation Saves Developers Time - This one is great on so many levels. It gives a short, pithy message with "AI-Powered ATF Testing" followed by a longer, more descriptive sub-title. This split can help you achieve a balance between fun titles and meaningful titles. It also is a great reminder that long titles can be a great way to differentiate from other similar articles.

Bad Examples

• Time Zones: Why You Punish Me - Sure, it's a great Hootie and the Blowfish reference but would you, dear reader, guess that it was about GlideDateTime and the complexities of working with time zones?  Maybe, maybe not. It's not particularly clear or descriptive. I tried to get too clever with this one. A better title might have been Understanding Time Zones when working with Service Portal and GlideDateTime.
• Is GlideRecord getValue the King of the String - I love this title. I do. But I hear all the time about how people almost missed this gem because of the title. Once again, I tried to be a little too clever. A better title would have been Should I use getValue or toString when working with GlideRecord.

Breaking Rules

• Configuration vs Customization: Which Is It? - Technically a presentation but still relevant. The content completely undermines the title which technically violates both the clear and descriptive criteria. But the title is intentionally baiting on a well-known debate in order to reframe the conversation. In this way, the title is misleading but satisfyingly so for the reader. Sometimes, rules are meant to be broken.

Structure Your Content

Oddly enough, not everyone reads the same way. Some readers will read the entire article, some will simply scan it, some will skip around. Be kind to your reader, structure your content to ensure it is easy to navigate, regardless of reading style. There are a few things you can do ensure your content is navigable:

1. Use headings: Headings make content infinitely more scannable. Headings should summarize the key points of the article. If the reader can grasp the main points by only reading the headings, you've nailed it.
2. Use whitespace: Whitespace is extremely important for visual hierarchy. Headings are easier to spot when there is a little more space between them and the text preceding it. Conversely, text that provides details for the heading should be closer. You can also use whitespace around code blocks or important one-line paragraphs. A good command of white space will draw the readers eyes to the important parts.
3. Use bold text sparingly: Bold text can draw a lot of attention and be very distracting when overused. Typically, you should bold as few words as possible to get your point across. Same rule applies for words in ALL CAPS and other "loud" text.
4. Use code blocks: Code blocks are a great way to visually differentiate code from other body text. Code outside of a code block can make it harder to parse the difference between the code and the body text.

   var incident = new GlideRecord('incident');

5. Use consistent fonts and sizes: Body text is body text and should look like other body text. Heading text is heading text and should look like other heading text. Avoid the temptation to make one off changes like making one word in the body text a larger font size than the rest. Your choices of font, size, and color should communicate something. Be consistent in those choices and avoid the appearance of randomness.
6. Incorporate Visuals: Graphics, screenshots, and icons are a great way to enhance the quality of your article and they also reinforce the structure. These visuals can make larger articles easier to scan and can reinforce topics for visual learners. Take a look at this article's use of graphics and how each graphic reflects the heading it is under. Or this article's use of emoji to visually differentiate the bullet points in different sections.

Using a consistent set of rules for the visual structure of your article can make it infinitely easier for readers to navigate the information you've provided.

Add Original Insights

The one thing that sets your blog apart from all the others is you. Your unique perspective is something no one else has. To truly elevate your content, you need to find a way to incorporate your experiences, perspectives, and insights. 

When you share announcements about new features, try to elevate that content by sharing a time you wish you had that feature before. Or by sharing how you plan to use the feature in your day-to-day work.

When you share excerpts of other people's content, elevate it by telling how the content helped you specifically. Why did you find the content interesting? What experiences have you had that made the content you are sharing relatable to you?

When you share new certifications or accomplishments, consider sharing specifics about how you prepared or what you did to get to where you are. Take those moments as an opportunity to share your journey, what worked, and what didn't.

Your insights and experiences are more important to others than you may realize. So be sure to share them!

Conclusion

Writing a blog article is both an art and a skill that can profoundly impact readers. By carefully crafting compelling titles, structuring your content for easy navigation, and incorporating your unique insights and experiences, you can be well on your way to writing articles that leave a lasting impression.