Blog Guidance

Ready to create a blog article? Here’s some guidance to get you started:

  • Ensure your article has been through a peer and/or tech review for accuracy.

  • Use a conversational writing style. If you prefer formality, that’s fine.

For additional guidance, see Getting Started on the Community Site: Concise Blog Post Style Guide

Overview:

Provide a brief and precise explanation of the use case letting the reader know what will be achieved. Users read content for the value it offers.

This tells the reader they’re in the right place, and you understand their problem or use case outcome they want to achieve.

Write short, concise steps equivalent to one or two actions.

(E.g., Choose Add Users from the Actions menu.

Code Snippets

Provide example code snippets to demonstrate how to use the code/command and expected response.

Tutorials

Tutorials (How-to and instructional videos): create an informal video or screen recordings designed to teach someone how to perform a task or procedure, similar to a recorded TOI. Research shows that people prefer to consult a video tutorial when looking for answers to their questions. In fact: 83% of people prefer watching videos to accessing instructional or informational content via text or audio.

Screenshots

Avoid the “Wall of Text” when creating content. Format the text and use images (UI, CLI, IDE, terminal, etc.)to illustrate the use case and encourage reader engagement.

Error and debugging details

Demonstrate potential Error and status codes that can be returned, and at what endpoints etc they may occur? Offer Solutions to common errors.

Links to Relevant Resources

Internal and external links provide a more in-depth experience for the user. The intention is to lead to companion content or related information that compliments and doesn’t duplicate the content in your blog. Anything that helps your reader get more information, such as Product documentation, Knowledge Base articles, and RFCs, for example.

Don’t make the reader Google “how to…”, or dig through documentation. Always provide a direct link to the resource to improve the user experience and site interaction.

See the community New User Guide for some further guidance to get you started creating your new blog!

Next month will dive into what makes a good solution article.

3 Likes