Skip to main content

Writing Your Blog Post

Content Guidelines​

  • Originality: Content should be original. If referencing external sources, cite them appropriately.

  • Clarity and Conciseness: Use clear and concise language, avoiding jargon and technical terms where possible.

  • Structure and Formatting: Organize your content with headings, subheadings, bullet points, and visuals to enhance readability.

  • Tone and Style: Maintain a professional and informative tone, while also being engaging and approachable.

  • Visuals: Use images, diagrams, and other visuals to illustrate concepts and break up text.

  • Confidentiality: Do not disclose any confidential or sensitive information about IO or its projects.

  • Accessibility: Ensure posts are easy to read and navigate for all levels of technical expertise.

  • Length: Aim for 800-1500 words. Blog posts should be concise but insightful.

Diversity, Inclusion, and Belonging (DIB) checklist for blog writers​

It is important that our blog content represents our company values of diversity, inclusion, and belonging. Not all of these points will be relevant to your blog post, but they are important values and practices to be mindful of throughout the writing process. The blog editorial team tries to check for these things, but it is better if all content is created with these values and practices in mind.

Preparing images​

  • If creating an original cover image, the dimensions should be 1800px x 945px for optimal quality on all displays.

  • All images should aim to be less than 1MB. JPEGs tend to be smaller than PNGs so use JPEGs when possible.

  • To resize in Preview go to Tools, Adjust size and adjust the entry in the Resolution field. Preview will estimate what

  • the resulting image size will be before you click OK to confirm.

  • Keep all the images the same width.

Screenshots​

For technical/tutorial posts, please illustrate your examples with code blocks or screenshots. Be consistent with your examples. E.g., if you are using a generic URL to exemplify your steps domain.com, be consistent and keep it domain.com, throughout the post.

  • Static images should be used to illustrate concepts, provide diagrams, elements of the UI or orient the reader.

  • Images should not be used to render commands or configuration which would prevent someone being able to copy and paste.

  • Animated GIFs can be used sparingly where you need to show a process or some event happening over the course of time or

  • several actions, though they should not replace text descriptions or instructions.

  • Use screenshots to identify and localize specific parts of the screen. There are great tools for doing so. For example,

  • Nimbus Screenshot (browser extension), Mac screenshot, Snipping Tool for Windows, and Screenshot Tool for Ubuntu.

Important security point: Do not expose your personal details by using your real tokens or security credentials. Use placeholders such as [project's CI token] stub instead. Or blur them if displayed on screenshots.