Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion guide/contribute/formatting/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
42 changes: 40 additions & 2 deletions guide/contribute/propose-a-change.md
Original file line number Diff line number Diff line change
Expand Up @@ -174,16 +174,54 @@ 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 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.
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 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](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.

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.

[^1]:[Creating, cloning and archiving repositories](https://docs.github.com/en/enterprise-server@3.0/github/creating-cloning-and-archiving-repositories/about-repositories)
[^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**

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 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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure this belongs in the checklist per se. IIRC this is also explained in the Content guidelines section.

@GBKS GBKS Oct 21, 2024 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that's fine. This checklist is a bit of a summary of things that are explained in more detail elsewhere, so some repetition is OK.

- 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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be done just before merging or after all images are finalised...otherwise user has to remember to do it every time they change an image... not sure how this can be communicated.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you use a tool like ImageOptim, it will not compress images twice. Just drag all your pics in, let it do its thing, and you're good to go.

- Delete unused images from your PR

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This might be hard to detect if a mistake is made.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, but it has to be done.

- 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/).
Expand Down