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/01-overview.md b/docs/qe-blog/01-overview.md new file mode 100644 index 0000000..8d41d9e --- /dev/null +++ b/docs/qe-blog/01-overview.md @@ -0,0 +1,32 @@ +--- +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 + +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..aa380f3 --- /dev/null +++ b/docs/qe-blog/02-who-can-contribute.md @@ -0,0 +1,12 @@ +--- +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. + +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..ac78597 --- /dev/null +++ b/docs/qe-blog/03-content-submission-process.md @@ -0,0 +1,65 @@ +--- +title: Content Submission Process +metaTitle: Content Submission Process +--- + +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). + +### 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..34b3507 --- /dev/null +++ b/docs/qe-blog/04-content-guidelines.md @@ -0,0 +1,60 @@ +--- +title: Writing Your Blog Post +metaTitle: 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..92471c7 --- /dev/null +++ b/docs/qe-blog/05-suggest-change.md @@ -0,0 +1,10 @@ +--- +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: + +* 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..550186f --- /dev/null +++ b/docs/qe-blog/06-contact-us.md @@ -0,0 +1,8 @@ +--- +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: + +* 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..af1c82c --- /dev/null +++ b/docs/qe-blog/_category_.yaml @@ -0,0 +1,4 @@ +position: 4 +label: 'QE Blog Guidelines' +collapsible: true +collapsed: true