From 2c958fb02dc0c813729c1f8a77b4df776c6f1f76 Mon Sep 17 00:00:00 2001 From: Jermiah Joseph Date: Wed, 30 Oct 2024 10:45:35 -0400 Subject: [PATCH] fix: revise handbook introduction and contribute guidelines for clarity and better onboarding experience fix: lint files --- docs/General/index.md | 24 +++++++++-- docs/contributing/.pages | 2 +- docs/contributing/changelog.md | 2 - docs/contributing/index.md | 74 ++++++++++++++++++++++++++++++--- docs/onboarding/introduction.md | 4 -- 5 files changed, 89 insertions(+), 17 deletions(-) diff --git a/docs/General/index.md b/docs/General/index.md index b46e587a..febe616f 100644 --- a/docs/General/index.md +++ b/docs/General/index.md @@ -1,8 +1,8 @@ # Home -## Draft Structure: +## What is the handbook? - +The handbook is a collection of resources for the BHK Lab. It is intended to be a resource for all BHK Lab members to learn about the lab, its projects, and how to get involved. {% include-markdown "../../README.md" @@ -10,6 +10,22 @@ end="" %} -## Development Documentation +## Want to Contribute? + +If you're interested in contributing to the BHK Lab Handbook, we encourage +you to check out our **[Contributing Section][contributing-to-the-lab-handbook]**. + +Whether you're looking to [report an issue][submitting-issues], +[add new content][adding-content], or +[suggest an enhancement][submitting-issues], the [Contributing Section][contributing-to-the-lab-handbook] has all +the resources you need to get started. Your contributions help make this +handbook a valuable tool for the entire lab community! + +!!! warning "This handbook is under active development and open-source!" -See [Contributing to the Lab Handbook][contributing-to-the-lab-handbook] for more information. + Visit the [GitHub repository](https://github.com/bhklab/handbook) to + see the latest updates and contribute to the project. + +## Miro Board: + + diff --git a/docs/contributing/.pages b/docs/contributing/.pages index 8f5764f9..a7d35199 100644 --- a/docs/contributing/.pages +++ b/docs/contributing/.pages @@ -3,10 +3,10 @@ title: Contributing nav: - index.md - prerequisites.md + - submitting_issues.md - adding_content.md - ... - reviews.md - merging_pr.md - release_deployment.md - - submitting_issues.md - changelog.md diff --git a/docs/contributing/changelog.md b/docs/contributing/changelog.md index 7c084d92..1fb64d6e 100644 --- a/docs/contributing/changelog.md +++ b/docs/contributing/changelog.md @@ -1,5 +1,3 @@ {% include-markdown "../../CHANGELOG.md" - start="" - end="" %} diff --git a/docs/contributing/index.md b/docs/contributing/index.md index cfb6babb..bd74e487 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -1,12 +1,74 @@ # [Contributing to the Lab Handbook](#contributing-to-the-lab-handbook) -Thank you for your interest in contributing to the Lab Handbook! This section will guide you through the process of setting up your development environment, installing dependencies, and building the documentation. +*Thank you for your interest in contributing to the Lab Handbook!* -## Getting Started +This section will guide you through the process of setting up your +development environment, installing dependencies, and building the documentation. -Before you begin, you should have the following: +Below are some common questions to help you find the right guidance for specific +contributing tasks. -1. A [GitHub](https://github.com/) account. -2. [`pixi`](https://pixi.sh/) installed. +--- -See [Prerequisites][prerequisites] for more information. +## Where should I start if I want to contribute? + +If you’re new to contributing, start with the **[Prerequisites](prerequisites.md)** +page to set up your environment and install necessary dependencies. + +--- + +## How do I submit an issue for a problem I found? + +If you’ve identified an issue, refer to the +**[Submitting Issues](submitting_issues.md)** page.
It provides details on +how to use our issue templates and submit effective bug reports or feature requests. + +--- + +## How can I add new content to the handbook? + +To learn about adding or editing content, check out the +**[Adding Content](adding_content.md)** page.
This guide explains how to +structure and format your additions to fit seamlessly into the handbook. + + +--- + +## What steps are involved in the review process? + +The **[Reviewing a Contribution](reviews.md)** page outlines the review process, +including best practices for constructive feedback and steps for both reviewers +and contributors. + +--- + +## Where can I view all the changes made to the handbook? + +To see recent updates and changes to the documentation, visit the +**[Changelog](changelog.md)** page for a record of all documented changes. + +--- + +By following these resources, you'll have everything you need to contribute +effectively to the Lab Handbook. If you have additional questions, feel free +to reach out to the maintainers or submit a question through the +**[Submitting Issues](submitting_issues.md)** page. + +___ + +# For Maintainers + +## What should I know about merging pull requests? + +For guidance on merging contributions, visit the **[Merging PR](merging_pr.md)** +page.
It explains our review process, how to address review comments, and +merge a PR successfully. + +--- + +## How do I prepare for releasing and deploying changes? + +Check out the [Release & Deployment](release_deployment.md) page to learn +about our release procedures, automated workflows, and deployment to GitHub Pages. + +--- diff --git a/docs/onboarding/introduction.md b/docs/onboarding/introduction.md index 0a4dc72a..a463177f 100644 --- a/docs/onboarding/introduction.md +++ b/docs/onboarding/introduction.md @@ -1,5 +1 @@ # Onboarding Introduction - -## What is the handbook? - -The handbook is a collection of resources for the BHK Lab. It is intended to be a resource for all BHK Lab members to learn about the lab, its projects, and how to get involved.