Skip to content

Commit a7d14db

Browse files
authored
added blog contribution guidelines (#44)
* added blog contribution guidelines * added category/order for the Knowledge Hub section * updated page titles
1 parent e64e30a commit a7d14db

File tree

8 files changed

+195
-0
lines changed

8 files changed

+195
-0
lines changed

docs/knowledge-hub/_category_.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
position: 3
2+
label: 'Knowledge Hub'
3+
collapsible: true
4+
collapsed: true

docs/qe-blog/01-overview.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: Overview
3+
metaTitle: Overview
4+
---
5+
6+
## Welcome!
7+
8+
We're excited you're interested in contributing to the [IO Quality Engineering Blog](https://input-output-hk.github.io/quality-engineering/blog/).
9+
This is a platform to share your expertise, insights, and experiences with the wider IOG community and beyond.
10+
These guidelines will help you understand the process and ensure your contributions are aligned with our goals.
11+
12+
## Purpose of the Blog
13+
14+
The IOG Quality Engineering blog serves as a collaborative platform to share knowledge, insights, and proven practices across
15+
the entire software development lifecycle (SDLC), from proof of concept and feature specification to implementation, validation, and delivery.
16+
It aims to foster a culture of continuous learning and improvement across the organization and community by:
17+
18+
* **Success Stories from the Front Lines:** Explore real-world examples of how IOG has applied innovative QE techniques to streamline development, enhance quality, and accelerate delivery.
19+
20+
* **IOG-Specific Initiatives:** Highlight internal projects, processes, or innovations that are unique to IOG's approach to quality.
21+
22+
* **Case Studies:** Showcase real-world examples of how IOG applied QE principles and practices across the SDLC to achieve successful project outcomes.
23+
24+
* **Formal Methods Integration:** Discuss how IOG integrates formal methods into different stages of the SDLC to enhance software quality.
25+
26+
* **Security Considerations:** Highlight security best practices and how they are implemented throughout the SDLC at IOG.
27+
28+
* **Integrating Quality and UX:** Explore how quality engineering practices can be applied to ensure a positive user experience (UX) throughout the SDLC, including usability testing, accessibility considerations, and user feedback integration.
29+
30+
* **Quality Metrics and Reporting:** Share insights into relevant quality metrics and how to use them to track progress and identify areas for improvement.
31+
32+
* **Lessons Learned and Proven Practices:** Gain valuable insights from IOG's diverse experiences, including the challenges faced and the solutions developed.
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: Who Can Contribute?
3+
metaTitle: Who Can Contribute?
4+
---
5+
6+
**We welcome contributions from everyone at IO**, across all departments involved in any aspect of software products.
7+
This includes, but is not limited to, team members from marketing, communications, business, product, technology, delivery, and other relevant functions.
8+
9+
For the blog, this means you are encouraged to propose ideas, share suggestions, and submit draft content on topics related to software quality and the broader landscape of Quality Engineering.
10+
11+
While we encourage broad participation, it's important to remember that the blog is an official communication channel for IO.
12+
To ensure we consistently present accurate and high-quality information, all content undergoes a review process led by the Head of Quality Engineering, who serves as the Directly Responsible Individual (DRI) for the blog.
Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: Content Submission Process
3+
metaTitle: Content Submission Process
4+
---
5+
6+
Blog posts should focus on sharing helpful information with the audience. When you suggest or write a blog post,
7+
always consider what it offers the reader. If the post is more internal-focused or a personal essay of sorts, it is
8+
likely not a fit for this blog (but could go on Confluence or on your personal LinkedIn page).
9+
10+
### 1\. Propose Your Idea
11+
12+
* Before drafting a blog post, contributors should submit a blog proposal. This ensures alignment with the QE blog's goals and prevents overlap with other content.
13+
14+
* The proposal should include:
15+
16+
* **Proposed Title**: A concise, descriptive title.
17+
18+
* **Summary**: 2-3 sentences summarizing the core idea of the post.
19+
20+
* **Audience**: Specify the target audience (e.g., developers, testers, leadership, etc.).
21+
22+
* **Key Takeaways:** Outline 3-5 takeaways for readers.
23+
24+
* **Draft Timeline**: Suggested timeline for draft submission and publication.
25+
26+
27+
**Where to submit:** Reach out to the QE blog editorial team or use the internal [blog submission template](https://github.com/input-output-hk/quality-engineering/issues/new?assignees=&labels=blog&projects=&template=blog.md&title=)
28+
to submit your proposal to the blog editorial team.
29+
30+
The QE blog editorial team will review the pitch and either a) greenlight the post, b) offer suggestions for improvements,
31+
or c) explain why the idea might not be a fit for the blog and offer other ideas for getting the message out.
32+
33+
### 2\. Draft the Blog Post
34+
35+
* Once the proposal is approved, the contributor can start drafting the blog post.
36+
37+
38+
### 3\. Draft Review and Editing
39+
40+
* Submit the completed draft to the QE blog editorial team for review.
41+
42+
* The review process will check:
43+
44+
* Grammar, spelling, and clarity
45+
46+
* Adherence to IOG brand tone and style
47+
48+
* Accuracy and technical correctness
49+
50+
* Content length and readability
51+
52+
* The editorial team may request revisions before the post is approved for publication.
53+
54+
55+
### 4\. Publication
56+
57+
Once the draft is finalized and approved:
58+
59+
* The blog post will be scheduled for publication based on content planning and calendar.
60+
61+
* The QE blog editorial team will handle the actual publishing process on the platform ([Blog | Quality Engineering](https://input-output-hk.github.io/quality-engineering/blog/)).
62+
63+
* The author will be credited on the post, with a short bio (optional).
64+
65+
* The contributor will be notified of the expected publication date.
Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
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.

docs/qe-blog/05-suggest-change.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: How to suggest a change to a published blog
3+
metaTitle: How to suggest a change to a published blog
4+
---
5+
6+
If you want to suggest a change to a published IO QE blog, please post the change you need in detail using one of the below options:
7+
8+
* If you are external to IO, please email @Dorin Solomon at `dorin.solomon@iohk.io` with the details of your suggested change.
9+
10+
* open an [Issue: feedback](https://github.com/input-output-hk/quality-engineering/issues/new/choose) directly on our repository

docs/qe-blog/06-contact-us.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: Communication with QE Blog Editorial team
3+
metaTitle: Communication with QE Blog Editorial team
4+
---
5+
6+
For any inquiries or assistance with your IO QE blog proposal or draft:
7+
8+
* Slack @Dorin Solomon directly or send an email to `dorin.solomon@iohk.io`

docs/qe-blog/_category_.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
position: 4
2+
label: 'QE Blog Guidelines'
3+
collapsible: true
4+
collapsed: true

0 commit comments

Comments
 (0)