From 80066d605d36cd54f9c0432656d748f02bff7118 Mon Sep 17 00:00:00 2001 From: dorin solomon Date: Thu, 24 Oct 2024 11:32:23 +0300 Subject: [PATCH 1/3] added blog contribution guidelines --- docs/qe-blog/01-overview.md | 29 +++++++++ docs/qe-blog/02-who-can-contribute.md | 10 +++ docs/qe-blog/03-content-submission-process.md | 63 +++++++++++++++++++ docs/qe-blog/04-content-guidelines.md | 58 +++++++++++++++++ docs/qe-blog/05-suggest-change.md | 8 +++ docs/qe-blog/06-contact-us.md | 6 ++ docs/qe-blog/_category_.yaml | 4 ++ 7 files changed, 178 insertions(+) create mode 100644 docs/qe-blog/01-overview.md create mode 100644 docs/qe-blog/02-who-can-contribute.md create mode 100644 docs/qe-blog/03-content-submission-process.md create mode 100644 docs/qe-blog/04-content-guidelines.md create mode 100644 docs/qe-blog/05-suggest-change.md create mode 100644 docs/qe-blog/06-contact-us.md create mode 100644 docs/qe-blog/_category_.yaml diff --git a/docs/qe-blog/01-overview.md b/docs/qe-blog/01-overview.md new file mode 100644 index 0000000..026984f --- /dev/null +++ b/docs/qe-blog/01-overview.md @@ -0,0 +1,29 @@ +Welcome! +-------- + +We're excited you're interested in contributing to the [IO Quality Engineering Blog](https://input-output-hk.github.io/quality-engineering/blog/). +This is a platform to share your expertise, insights, and experiences with the wider IOG community and beyond. +These guidelines will help you understand the process and ensure your contributions are aligned with our goals. + +Purpose of the Blog +------------------- + +The IOG Quality Engineering blog serves as a collaborative platform to share knowledge, insights, and proven practices across +the entire software development lifecycle (SDLC), from proof of concept and feature specification to implementation, validation, and delivery. +It aims to foster a culture of continuous learning and improvement across the organization and community by: + +* **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. + +* **IOG-Specific Initiatives:** Highlight internal projects, processes, or innovations that are unique to IOG's approach to quality. + +* **Case Studies:** Showcase real-world examples of how IOG applied QE principles and practices across the SDLC to achieve successful project outcomes. + +* **Formal Methods Integration:** Discuss how IOG integrates formal methods into different stages of the SDLC to enhance software quality. + +* **Security Considerations:** Highlight security best practices and how they are implemented throughout the SDLC at IOG. + +* **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. + +* **Quality Metrics and Reporting:** Share insights into relevant quality metrics and how to use them to track progress and identify areas for improvement. + +* **Lessons Learned and Proven Practices:** Gain valuable insights from IOG's diverse experiences, including the challenges faced and the solutions developed. diff --git a/docs/qe-blog/02-who-can-contribute.md b/docs/qe-blog/02-who-can-contribute.md new file mode 100644 index 0000000..e34fdf1 --- /dev/null +++ b/docs/qe-blog/02-who-can-contribute.md @@ -0,0 +1,10 @@ +Who Can Contribute? +------------------- + +**We welcome contributions from everyone at IO**, across all departments involved in any aspect of software products. +This includes, but is not limited to, team members from marketing, communications, business, product, technology, delivery, and other relevant functions. + +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. + +While we encourage broad participation, it's important to remember that the blog is an official communication channel for IO. +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. diff --git a/docs/qe-blog/03-content-submission-process.md b/docs/qe-blog/03-content-submission-process.md new file mode 100644 index 0000000..c878bcb --- /dev/null +++ b/docs/qe-blog/03-content-submission-process.md @@ -0,0 +1,63 @@ +Content Submission Process +-------------------------- + +At IO Quality Engineering, blog posts largely focus on sharing helpful information with the audience. When you suggest or write a blog post, +always consider what it offers the reader. If the post is more internal-focused or a personal essay of sorts, it is +likely not a fit for this blog (but could go on Confluence or on your personal LinkedIn page). + +### 1\. Propose Your Idea + +* 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. + +* The proposal should include: + + * **Proposed Title**: A concise, descriptive title. + + * **Summary**: 2-3 sentences summarizing the core idea of the post. + + * **Audience**: Specify the target audience (e.g., developers, testers, leadership, etc.). + + * **Key Takeaways:** Outline 3-5 takeaways for readers. + + * **Draft Timeline**: Suggested timeline for draft submission and publication. + + +**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=) +to submit your proposal to the blog editorial team. + +The QE blog editorial team will review the pitch and either a) greenlight the post, b) offer suggestions for improvements, +or c) explain why the idea might not be a fit for the blog and offer other ideas for getting the message out. + +### 2\. Draft the Blog Post + +* Once the proposal is approved, the contributor can start drafting the blog post. + + +### 3\. Draft Review and Editing + +* Submit the completed draft to the QE blog editorial team for review. + +* The review process will check: + + * Grammar, spelling, and clarity + + * Adherence to IOG brand tone and style + + * Accuracy and technical correctness + + * Content length and readability + +* The editorial team may request revisions before the post is approved for publication. + + +### 4\. Publication + +Once the draft is finalized and approved: + +* The blog post will be scheduled for publication based on content planning and calendar. + +* 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/)). + +* The author will be credited on the post, with a short bio (optional). + +* The contributor will be notified of the expected publication date. diff --git a/docs/qe-blog/04-content-guidelines.md b/docs/qe-blog/04-content-guidelines.md new file mode 100644 index 0000000..427c412 --- /dev/null +++ b/docs/qe-blog/04-content-guidelines.md @@ -0,0 +1,58 @@ +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. diff --git a/docs/qe-blog/05-suggest-change.md b/docs/qe-blog/05-suggest-change.md new file mode 100644 index 0000000..af6333b --- /dev/null +++ b/docs/qe-blog/05-suggest-change.md @@ -0,0 +1,8 @@ +How to suggest a change to a published blog +------------------------------------------- + +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: + +* If you are external to IO, please email @Dorin Solomon at `dorin.solomon@iohk.io` with the details of your suggested change. + +* open an [Issue: feedback](https://github.com/input-output-hk/quality-engineering/issues/new/choose) directly on our repository diff --git a/docs/qe-blog/06-contact-us.md b/docs/qe-blog/06-contact-us.md new file mode 100644 index 0000000..ecb7d35 --- /dev/null +++ b/docs/qe-blog/06-contact-us.md @@ -0,0 +1,6 @@ +Communication with QE Blog Editorial team +----------------------------------------- + +For any inquiries or assistance with your IO QE blog proposal or draft: + +* Slack @Dorin Solomon directly or send an email to `dorin.solomon@iohk.io` diff --git a/docs/qe-blog/_category_.yaml b/docs/qe-blog/_category_.yaml new file mode 100644 index 0000000..b8b572c --- /dev/null +++ b/docs/qe-blog/_category_.yaml @@ -0,0 +1,4 @@ +position: 4 +label: 'Quality Engineering Blog' +collapsible: true +collapsed: true From 57f3d3b1db37bcd9f84543ceed8a9c9bfdbce585 Mon Sep 17 00:00:00 2001 From: dorin solomon Date: Thu, 24 Oct 2024 11:40:06 +0300 Subject: [PATCH 2/3] added category/order for the Knowledge Hub section --- docs/knowledge-hub/_category_.yaml | 4 ++++ docs/qe-blog/_category_.yaml | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 docs/knowledge-hub/_category_.yaml diff --git a/docs/knowledge-hub/_category_.yaml b/docs/knowledge-hub/_category_.yaml new file mode 100644 index 0000000..80f8149 --- /dev/null +++ b/docs/knowledge-hub/_category_.yaml @@ -0,0 +1,4 @@ +position: 3 +label: 'Knowledge Hub' +collapsible: true +collapsed: true diff --git a/docs/qe-blog/_category_.yaml b/docs/qe-blog/_category_.yaml index b8b572c..af1c82c 100644 --- a/docs/qe-blog/_category_.yaml +++ b/docs/qe-blog/_category_.yaml @@ -1,4 +1,4 @@ position: 4 -label: 'Quality Engineering Blog' +label: 'QE Blog Guidelines' collapsible: true collapsed: true From 2079a13f4b98f46d47772b4167b030c002754f70 Mon Sep 17 00:00:00 2001 From: dorin solomon Date: Thu, 24 Oct 2024 12:07:26 +0300 Subject: [PATCH 3/3] updated page titles --- docs/qe-blog/01-overview.md | 11 +++++++---- docs/qe-blog/02-who-can-contribute.md | 6 ++++-- docs/qe-blog/03-content-submission-process.md | 8 +++++--- docs/qe-blog/04-content-guidelines.md | 6 ++++-- docs/qe-blog/05-suggest-change.md | 6 ++++-- docs/qe-blog/06-contact-us.md | 6 ++++-- 6 files changed, 28 insertions(+), 15 deletions(-) diff --git a/docs/qe-blog/01-overview.md b/docs/qe-blog/01-overview.md index 026984f..8d41d9e 100644 --- a/docs/qe-blog/01-overview.md +++ b/docs/qe-blog/01-overview.md @@ -1,12 +1,15 @@ -Welcome! --------- +--- +title: Overview +metaTitle: Overview +--- + +## Welcome! We're excited you're interested in contributing to the [IO Quality Engineering Blog](https://input-output-hk.github.io/quality-engineering/blog/). This is a platform to share your expertise, insights, and experiences with the wider IOG community and beyond. These guidelines will help you understand the process and ensure your contributions are aligned with our goals. -Purpose of the Blog -------------------- +## Purpose of the Blog The IOG Quality Engineering blog serves as a collaborative platform to share knowledge, insights, and proven practices across the entire software development lifecycle (SDLC), from proof of concept and feature specification to implementation, validation, and delivery. diff --git a/docs/qe-blog/02-who-can-contribute.md b/docs/qe-blog/02-who-can-contribute.md index e34fdf1..aa380f3 100644 --- a/docs/qe-blog/02-who-can-contribute.md +++ b/docs/qe-blog/02-who-can-contribute.md @@ -1,5 +1,7 @@ -Who Can Contribute? -------------------- +--- +title: Who Can Contribute? +metaTitle: Who Can Contribute? +--- **We welcome contributions from everyone at IO**, across all departments involved in any aspect of software products. This includes, but is not limited to, team members from marketing, communications, business, product, technology, delivery, and other relevant functions. diff --git a/docs/qe-blog/03-content-submission-process.md b/docs/qe-blog/03-content-submission-process.md index c878bcb..ac78597 100644 --- a/docs/qe-blog/03-content-submission-process.md +++ b/docs/qe-blog/03-content-submission-process.md @@ -1,7 +1,9 @@ -Content Submission Process --------------------------- +--- +title: Content Submission Process +metaTitle: Content Submission Process +--- -At IO Quality Engineering, blog posts largely focus on sharing helpful information with the audience. When you suggest or write a blog post, +Blog posts should focus on sharing helpful information with the audience. When you suggest or write a blog post, always consider what it offers the reader. If the post is more internal-focused or a personal essay of sorts, it is likely not a fit for this blog (but could go on Confluence or on your personal LinkedIn page). diff --git a/docs/qe-blog/04-content-guidelines.md b/docs/qe-blog/04-content-guidelines.md index 427c412..34b3507 100644 --- a/docs/qe-blog/04-content-guidelines.md +++ b/docs/qe-blog/04-content-guidelines.md @@ -1,5 +1,7 @@ -Writing Your Blog Post ----------------------- +--- +title: Writing Your Blog Post +metaTitle: Writing Your Blog Post +--- ### Content Guidelines diff --git a/docs/qe-blog/05-suggest-change.md b/docs/qe-blog/05-suggest-change.md index af6333b..92471c7 100644 --- a/docs/qe-blog/05-suggest-change.md +++ b/docs/qe-blog/05-suggest-change.md @@ -1,5 +1,7 @@ -How to suggest a change to a published blog -------------------------------------------- +--- +title: How to suggest a change to a published blog +metaTitle: How to suggest a change to a published blog +--- 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: diff --git a/docs/qe-blog/06-contact-us.md b/docs/qe-blog/06-contact-us.md index ecb7d35..550186f 100644 --- a/docs/qe-blog/06-contact-us.md +++ b/docs/qe-blog/06-contact-us.md @@ -1,5 +1,7 @@ -Communication with QE Blog Editorial team ------------------------------------------ +--- +title: Communication with QE Blog Editorial team +metaTitle: Communication with QE Blog Editorial team +--- For any inquiries or assistance with your IO QE blog proposal or draft: