From 2e5d5f31b4b004ff15e9773c9f6ea752509fd16b Mon Sep 17 00:00:00 2001 From: GBKS Date: Tue, 24 Sep 2024 11:28:33 +0200 Subject: [PATCH 1/4] Contribute page refinements - Expands on the process for requesting reviews and proposes a 3-step structure - Add a common issues checklist for general and smaller things to look out for before requesting reviews --- guide/contribute/propose-a-change.md | 42 ++++++++++++++++++++++++++-- 1 file changed, 40 insertions(+), 2 deletions(-) diff --git a/guide/contribute/propose-a-change.md b/guide/contribute/propose-a-change.md index e56f9e44e..5416a5596 100644 --- a/guide/contribute/propose-a-change.md +++ b/guide/contribute/propose-a-change.md @@ -174,9 +174,19 @@ After changes have been published on your copy, it's time to announce them in th height = 400 %} -#### Applying additional changes +#### Request a review -Your proposed changes need to undergo a [review process]({{ '/guide/contribute/review/' | relative_url }}). During the review of your pull request, you may be asked to make certain changes. To do that, simply make sure that you're on the same branch as the pull request you've submitted. [Apply and push](#applying-changes) your changes. +Your proposed changes need to undergo a [review process]({{ '/guide/contribute/review/' | relative_url }}). It often consists of several rounds of several rounds of feedback, for example: + +1. **Structural:** Reviewers look at how the new content fits in with the existing content in the guide. They check if it's generally appropriate, complete and accurate, and if it reads well. It gives you confidence that you are working in the right direction. +2. **Refinement:** This is about ensuring the content (text and visuals) is accurate, well-written, and communicates well. Several rounds may be needed. +3. **Polish:** Here we make the final content tweaks, like ensuring that there are no typos, everything renders correctly across devices, images have alt texts, etc. Once complete, the pull request can be approved and merged. + +This is generalized and your process may look different. In your pull request, and when requesting reviews, make sure to clearly communicate the type of feedback you are looking for. This makes the review task easier and more focused, and leads to more helpful responses. + +The community may not automatically see when you post a new pull request. Make sure to ask in the [#bitcoin-design-guide](https://discord.gg/7Z6z8cetwu) Discord channel, and reach out to reviewers whose specific feedback you would appreciate. You can also organize a reading sessions for your content, so far they have always been extremely helpful. + +During the review of your pull request, you may be asked to make certain changes. To do that, simply make sure that you're on the same branch as the pull request you've submitted. [Apply and push](#applying-changes) your changes. Once there is a consensus on the proposed changes, your pull request will be merged, and your changes will become part of the Bitcoin Design Guide. @@ -184,6 +194,34 @@ Once there is a consensus on the proposed changes, your pull request will be mer [^2]:[Branches in a nutshell](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) [^3]: [Committing and reviewing changes](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/committing-and-reviewing-changes-to-your-project#about-commits) +#### Common issues checklist + +There have been over 600 pull requests on this project, and we have noticed some points of feedback that regularly come up. If you look out for those before requesting reviews, the overall process will be smoother. + +**Front matter** + +This are the page properties at the top of markdown files, between the dividers ("---"). +- Ensure the page preview image is 1200x630px in size, and different from the banner image +- _redirect_from_ means that this page previously existed at a different URL. It is not needed for new pages + +**Content** +- Write in sentence case, not title case +- Lowercase "bitcoin", "lightning network" and "ecash" +- Make sure to explain less-widely known technical terms before expecting users to understand their meaning and properties +- If a new page is a sub-section, make sure to include a reference in the section landing page ([example](https://bitcoin.design/guide/how-it-works/)) +- A simpler writing style allows your content to be more accessible to more readers (especially ones for whom english is not their native language) +- For new pages, make sure to update the "Next" and "Previous" buttons on the respective next and previous pages +- Look for opportunities to cross-reference other content in the guide. If somethig is already well-covered elsewhere, you can build on that + +**Images** +- Ensure image content (especially text in images) is legible on mobile devices +- Ensure image paths are correct +- Ensure "width" and "height" attributes in picture and image includes match the actual image dimensions +- For smallest file size, use the JPG file format for textured and photographic images, and PNG for images with mostly flat color +- Compress your images via tool like [ImageOptim](http://imageoptim.com) (can save ~70% of bandwidth) +- Delete unused images from your PR +- Every non-decorative image needs to have helpful alt text ([tips](https://www.w3.org/WAI/tutorials/images/tips/)) + --- Next, find out how you can [become a guide reviewer](/guide/contribute/review/). From 07f7bd4fc79d27e5846c8b354b2b9afe73483a7d Mon Sep 17 00:00:00 2001 From: Christoph Ono Date: Mon, 21 Oct 2024 15:10:36 +0200 Subject: [PATCH 2/4] Apply suggestions from code review Thanks to Yashraj for finding my various spelling mistakes and suggesting good tweaks. Co-authored-by: Max <114083781+yashrajd@users.noreply.github.com> --- guide/contribute/propose-a-change.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/guide/contribute/propose-a-change.md b/guide/contribute/propose-a-change.md index 5416a5596..e69b653db 100644 --- a/guide/contribute/propose-a-change.md +++ b/guide/contribute/propose-a-change.md @@ -176,15 +176,15 @@ After changes have been published on your copy, it's time to announce them in th #### Request a review -Your proposed changes need to undergo a [review process]({{ '/guide/contribute/review/' | relative_url }}). It often consists of several rounds of several rounds of feedback, for example: +Your proposed changes need to undergo a [review process]({{ '/guide/contribute/review/' | relative_url }}). It often consists of several rounds of feedback, for example: -1. **Structural:** Reviewers look at how the new content fits in with the existing content in the guide. They check if it's generally appropriate, complete and accurate, and if it reads well. It gives you confidence that you are working in the right direction. +1. **Structural:** Reviewers look at how the new content fits in with the existing content in the guide. They check if it's generally appropriate, complete and accurate. It gives you confidence that you are working in the right direction. 2. **Refinement:** This is about ensuring the content (text and visuals) is accurate, well-written, and communicates well. Several rounds may be needed. 3. **Polish:** Here we make the final content tweaks, like ensuring that there are no typos, everything renders correctly across devices, images have alt texts, etc. Once complete, the pull request can be approved and merged. -This is generalized and your process may look different. In your pull request, and when requesting reviews, make sure to clearly communicate the type of feedback you are looking for. This makes the review task easier and more focused, and leads to more helpful responses. +This is a generalization and your process may look different. In your pull request, and when requesting reviews, make sure to clearly communicate the type of feedback you are looking for. This makes the review task easier and more focused, and leads to more helpful responses. -The community may not automatically see when you post a new pull request. Make sure to ask in the [#bitcoin-design-guide](https://discord.gg/7Z6z8cetwu) Discord channel, and reach out to reviewers whose specific feedback you would appreciate. You can also organize a reading sessions for your content, so far they have always been extremely helpful. +The community may not automatically see when you post a new pull request. Make sure to ask in the [#bitcoin-design-guide](https://discord.gg/7Z6z8cetwu) Discord channel, and reach out to reviewers whose specific feedback you would appreciate. You can also organize a reading session for your content, so far they have always been extremely helpful. During the review of your pull request, you may be asked to make certain changes. To do that, simply make sure that you're on the same branch as the pull request you've submitted. [Apply and push](#applying-changes) your changes. @@ -200,14 +200,14 @@ There have been over 600 pull requests on this project, and we have noticed some **Front matter** -This are the page properties at the top of markdown files, between the dividers ("---"). +These are the page properties at the top of markdown files, between the dividers ("---"). - Ensure the page preview image is 1200x630px in size, and different from the banner image - _redirect_from_ means that this page previously existed at a different URL. It is not needed for new pages **Content** - Write in sentence case, not title case - Lowercase "bitcoin", "lightning network" and "ecash" -- Make sure to explain less-widely known technical terms before expecting users to understand their meaning and properties +- Make sure to explain new or lesser-known technical terms instead of expecting users to understand their meaning and properties - If a new page is a sub-section, make sure to include a reference in the section landing page ([example](https://bitcoin.design/guide/how-it-works/)) - A simpler writing style allows your content to be more accessible to more readers (especially ones for whom english is not their native language) - For new pages, make sure to update the "Next" and "Previous" buttons on the respective next and previous pages From 59753b090eddea08fa2b5765409ada04d0f224f9 Mon Sep 17 00:00:00 2001 From: GBKS Date: Mon, 11 Nov 2024 13:18:03 +0100 Subject: [PATCH 3/4] Minor formatting fix Tweaking the rendering of relative links, so the code is not pre-processed. The syntax shown on the site is now correct. Also adding an explainer for the reason why this syntax is necessary. --- guide/contribute/formatting/index.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/guide/contribute/formatting/index.md b/guide/contribute/formatting/index.md index 5e8c9576d..a04c300a1 100644 --- a/guide/contribute/formatting/index.md +++ b/guide/contribute/formatting/index.md @@ -102,9 +102,12 @@ There should be whitespace between paragraphs. #### Internal links +Formatting with `relative_url` is required for internal links, so the site can create correct links across any domain and sub-domain. + ```markdown -[Linking]({{ '/guide/getting-started/why-bitcoin-is-unique/' | relative_url }}) +{% raw %}[Linking]({{ '/guide/getting-started/why-bitcoin-is-unique/' | relative_url }}){% endraw %} ``` + [Linking]({{ '/guide/getting-started/why-bitcoin-is-unique/' | relative_url }}) #### Button links From 3b3e257aab97ecb01016d82dea92929d11a14757 Mon Sep 17 00:00:00 2001 From: Christoph Ono Date: Mon, 11 Nov 2024 13:33:39 +0100 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Mogashni <90313394+mouxdesign@users.noreply.github.com> --- guide/contribute/propose-a-change.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/contribute/propose-a-change.md b/guide/contribute/propose-a-change.md index e69b653db..a76c991fb 100644 --- a/guide/contribute/propose-a-change.md +++ b/guide/contribute/propose-a-change.md @@ -176,7 +176,7 @@ After changes have been published on your copy, it's time to announce them in th #### Request a review -Your proposed changes need to undergo a [review process]({{ '/guide/contribute/review/' | relative_url }}). It often consists of several rounds of feedback, for example: +Your proposed changes need to undergo a [review process]({{ '/guide/contribute/review/' | relative_url }}). It often consists of several rounds of feedback, these rounds usually include the following: 1. **Structural:** Reviewers look at how the new content fits in with the existing content in the guide. They check if it's generally appropriate, complete and accurate. It gives you confidence that you are working in the right direction. 2. **Refinement:** This is about ensuring the content (text and visuals) is accurate, well-written, and communicates well. Several rounds may be needed. @@ -184,7 +184,7 @@ Your proposed changes need to undergo a [review process]({{ '/guide/contribute/r This is a generalization and your process may look different. In your pull request, and when requesting reviews, make sure to clearly communicate the type of feedback you are looking for. This makes the review task easier and more focused, and leads to more helpful responses. -The community may not automatically see when you post a new pull request. Make sure to ask in the [#bitcoin-design-guide](https://discord.gg/7Z6z8cetwu) Discord channel, and reach out to reviewers whose specific feedback you would appreciate. You can also organize a reading session for your content, so far they have always been extremely helpful. +The community may not automatically see when you post a new pull request. Make sure to ask in the [#bitcoin-design-guide](https://discord.gg/7Z6z8cetwu) Discord channel, and reach out to reviewers whose specific feedback you would appreciate. You can also organize a [reading session](https://www.youtube.com/watch?v=hjgpNVRe4uY) for your content, so far they have always been extremely helpful. During the review of your pull request, you may be asked to make certain changes. To do that, simply make sure that you're on the same branch as the pull request you've submitted. [Apply and push](#applying-changes) your changes.