|
| 1 | +--- |
| 2 | +title: Writing Your Blog Post |
| 3 | +metaTitle: Writing Your Blog Post |
| 4 | +--- |
| 5 | + |
| 6 | +### Content Guidelines |
| 7 | + |
| 8 | +* **Originality:** Content should be original. If referencing external sources, cite them appropriately. |
| 9 | + |
| 10 | +* **Clarity and Conciseness:** Use clear and concise language, avoiding jargon and technical terms where possible. |
| 11 | + |
| 12 | +* **Structure and Formatting:** Organize your content with headings, subheadings, bullet points, and visuals to enhance readability. |
| 13 | + |
| 14 | +* **Tone and Style:** Maintain a professional and informative tone, while also being engaging and approachable. |
| 15 | + |
| 16 | +* **Visuals:** Use images, diagrams, and other visuals to illustrate concepts and break up text. |
| 17 | + |
| 18 | +* **Confidentiality:** Do not disclose any confidential or sensitive information about IO or its projects. |
| 19 | + |
| 20 | +* **Accessibility**: Ensure posts are easy to read and navigate for all levels of technical expertise. |
| 21 | + |
| 22 | +* **Length:** Aim for 800-1500 words. Blog posts should be concise but insightful. |
| 23 | + |
| 24 | + |
| 25 | +### Diversity, Inclusion, and Belonging (DIB) checklist for blog writers |
| 26 | + |
| 27 | +It is important that our blog content represents our company values of diversity, inclusion, and belonging. Not all of these |
| 28 | +points will be relevant to your blog post, but they are important values and practices to be mindful of throughout the writing process. |
| 29 | +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. |
| 30 | + |
| 31 | +### Preparing images |
| 32 | + |
| 33 | +* If creating an original cover image, the dimensions should be 1800px x 945px for optimal quality on all displays. |
| 34 | + |
| 35 | +* All images should aim to be less than 1MB. JPEGs tend to be smaller than PNGs so use JPEGs when possible. |
| 36 | + |
| 37 | +* To resize in Preview go to Tools, Adjust size and adjust the entry in the Resolution field. Preview will estimate what |
| 38 | +* the resulting image size will be before you click OK to confirm. |
| 39 | + |
| 40 | +* Keep all the images the same width. |
| 41 | + |
| 42 | + |
| 43 | +### Screenshots |
| 44 | + |
| 45 | +For technical/tutorial posts, please illustrate your examples with code blocks or screenshots. Be consistent with your examples. |
| 46 | +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. |
| 47 | + |
| 48 | +* Static images should be used to illustrate concepts, provide diagrams, elements of the UI or orient the reader. |
| 49 | + |
| 50 | +* Images should not be used to render commands or configuration which would prevent someone being able to copy and paste. |
| 51 | + |
| 52 | +* Animated GIFs can be used sparingly where you need to show a process or some event happening over the course of time or |
| 53 | +* several actions, though they should not replace text descriptions or instructions. |
| 54 | + |
| 55 | +* Use screenshots to identify and localize specific parts of the screen. There are great tools for doing so. For example, |
| 56 | +* Nimbus Screenshot (browser extension), Mac screenshot, Snipping Tool for Windows, and Screenshot Tool for Ubuntu. |
| 57 | + |
| 58 | + |
| 59 | +**Important security point:** Do not expose your personal details by using your real tokens or security credentials. |
| 60 | +Use placeholders such as \[project's CI token\] stub instead. Or blur them if displayed on screenshots. |
0 commit comments