diff --git a/guide/contribute/content-guidelines.md b/guide/contribute/content-guidelines.md index 7282d879d..340bba75a 100644 --- a/guide/contribute/content-guidelines.md +++ b/guide/contribute/content-guidelines.md @@ -3,7 +3,7 @@ layout: guide title: Content guidelines description: Writing tips for authors of the Bitcoin Design Guide. nav_order: 10 -parent: Contribute +parent: Contribute to guide permalink: /guide/contribute/content-guidelines/ image: /assets/images/guide/contribute/content-guidelines-preview.jpg --- @@ -12,57 +12,56 @@ image: /assets/images/guide/contribute/content-guidelines-preview.jpg The Bitcoin Design Guide is the work of many authors with different backgrounds, each with their own unique voice and perspective. To help us ensure a consistent written voice throughout the guide, follow these content guidelines. -#### Know your reader +### Know your reader -This guide is crafted for anyone interested in building an effective Bitcoin application. To understand who are you writing for, familiarize yourself with our [Target audience]({{ '/guide/target-audience' | relative_url }}). +This guide is crafted for anyone interested in building an effective Bitcoin application. To understand who you are writing for, familiarize yourself with our [Target audience]({{ '/guide/target-audience' | relative_url }}). -#### Speak to the reader +### Speak to the reader -Address the reader directly. Whenever possible, try using active instead of passive voice. Make reader a part the conversation by using second-person pronouns like "you, your and yours". Do not write in first-person and avoid giving predictions and personal opinions. - -##### Don't - -*My wallet balance is 1 bitcoin (BTC). If I have recently mined a block, this could be a fresh whole bitcoin. However, it is most likely going to be an accumulation of UTXOs (change) from previous bitcoin transactions.* +Address the reader directly. Whenever possible, try using active instead of passive voice. Make the reader a part the conversation by using second-person pronouns like "you, your and yours". Do not write in first-person and avoid giving predictions and personal opinions. ##### Do *Your wallet balance is 1 bitcoin (BTC). If you have recently mined a block, this could be a fresh whole bitcoin. However, it is most likely going to be an accumulation of UTXOs (change) from your previous bitcoin transactions.* +##### Don't + +*My wallet balance is 1 bitcoin (BTC). If I have recently mined a block, this could be a fresh whole bitcoin. However, it is most likely going to be an accumulation of UTXOs (change) from previous bitcoin transactions.* -#### Use simple language +### Use simple language Bitcoin is a global currency. Not everyone using this guide is a native English speaker. Make sure you are writing in plain, easy to follow English. If you're still not sure, try using a readability tool to analyze your text and make recommendations. We like [Hemingway](http://www.hemingwayapp.com). -#### Be concise +### Be concise Focus on information relevant to the reader. Use direct, clear, concise sentences that are easy to understand. Try to reduce the word count to just the right brevity without being obscure. -##### Don't - -*The wallet-application will generate a wallet with a keypair, then encrypt and back the key up to a location that the user is unlikely to lose access to, while hard for a malicious third party to gain access to.* - ##### Do *First the application generates a wallet with a keypair. Then, the key is encrypted and backed up to a location convenient and safe for the user, yet hard to for a malicious third-party to gain access to.* -#### Make content scannable +##### Don't + +*The wallet-application will generate a wallet with a keypair, then encrypt and back the key up to a location that the user is unlikely to lose access to, while hard for a malicious third party to gain access to.* + +### Make content scannable -On the internet, majority of people scans the content before reading it. By scanning, a reader tries to search for relevant information on the page. -Split text into paragraphs, use links, text styling and images to enhance the scanability. Per paragraph, you should have 3-4 sentences. +On the internet, most people scan the content before reading it. By scanning, a reader tries to search for relevant information on the page. +Split text into paragraphs, use links, text styling and images to make this easier. Each paragraph should ideally have no more than 3-4 sentences. -#### Linking +### Linking [Linking]({{ '/guide/contribute/formatting/#links' | relative_url }}) provides necessary context and helps avoid information repetition. Link to the [Glossary]({{ '/guide/glossary' | relative_url }}) or to another page in the guide whenever possible. If information isn't available, consider linking to a reputable third-party resource. -#### Give tips, not commands +### Give tips, not commands -When giving instruction, stick to broad strokes. They can be adjusted over time to grow with a project and its designer. Overly-detailed instructions could easily get outdated with the next software patch. +When describing solutions, stick to broad strokes. Overly-detailed instructions could easily get outdated with new technical developments. -#### Get the reader involved +### Get the reader involved The Design Guide is a set of recommended solutions and practices based on our research that should encourage self-sufficient thinking and creativity. Motivate people to think critically and inspire them to come up with their own solutions. -#### Show, don’t tell +### Show, don’t tell When it's possible, try to provide an example or a visual instead of highly-technical or text-heavy explanation. Feel free to reference other software using screenshots. @@ -76,14 +75,14 @@ When it's possible, try to provide an example or a visual instead of highly-tech *These UTXOs can also be grouped into “clusters” from the individual senders (see diagram)*. ![](assets/images/payments/cluster-options.png) -#### Use the right medium +### Use the right medium A picture is worth a thousand words, but so are videos, interactive prototypes, diagrams, and more. Don't be afraid to try a different medium if you think it will inform better than text or a picture. -#### Be humble +### Be humble The guide is a work in progress and needs to evolve to stay relevant. What we write today may not be applicable tomorrow. Have fun. Don't overthink things. Bitcoin, and therefore this guide, is the ultimate work-in-progress. -#### Write in the open +### Write in the open It's a good idea to ask for directions by seeking feedback early. This may stop you from wandering too far in the wrong direction. There is a whole community around you that's ready to jump in and help. diff --git a/guide/contribute/contribute.md b/guide/contribute/contribute.md index 4f1e0f5b0..a5ddbc8f9 100644 --- a/guide/contribute/contribute.md +++ b/guide/contribute/contribute.md @@ -1,6 +1,6 @@ --- layout: guide -title: Contribute +title: Contribute to guide description: Additional material for both readers and writers of the guide. nav_order: 9 has_children: true @@ -16,6 +16,19 @@ This page shows you how to get involved and start contributing. --- +**[Slack channel]({{ site.slack_invite_url }})** + +We use the #bitcoin-design-guide channel in the [Bitcoin Design Slack community]({{ site.slack_invite_url }}) to communicate and discuss work on guide. To hear what is going on, see what you can help with, or suggest new contributions please come and say hi. + +--- + +**[Github](https://github.com/BitcoinDesign/Guide)** + +We use Github to host the content of the guide. [Issues](https://github.com/BitcoinDesign/Guide/issues) are used to post ideas for improvements, and proposed changes are posted as [Pull Requests](https://github.com/BitcoinDesign/Guide/pulls). +For some ideas we use [Discussions](https://github.com/BitcoinDesign/Guide/discussions). + +--- + **[Content guidelines]({{ '/guide/contribute/content-guidelines/' | relative_url }})** Tips on how to write for the guide, with the goal of achieving a consistent tone across all pages. diff --git a/guide/contribute/formatting.md b/guide/contribute/formatting.md index 2fc505941..57a08d07d 100644 --- a/guide/contribute/formatting.md +++ b/guide/contribute/formatting.md @@ -3,14 +3,16 @@ layout: guide title: Formatting description: Visual examples of formatting options available for content authors. nav_order: 11 -parent: Contribute +parent: Contribute to guide permalink: /guide/contribute/formatting/ image: /assets/images/guide/contribute/formatting-preview.jpg --- # Formatting -This page showcases the various formatting and layout options available for content. This allows editors to better understand their toolbox and access reference code. It also allows for designers to see the design system in one place. The design source file is a public Figma community file you can find [here](https://www.figma.com/community/file/862622015964353400/Bitcoin-Designers-site). To improve the design, please start with the Figma file and make a proposal in Slack or Github before implementing. +This page showcases the various formatting and layout options available for content. This allows editors to better understand their toolbox and access reference code. It also allows for designers to see the design system in one place. + +The design source file is a public Figma community file you can find [here](https://www.figma.com/community/file/862622015964353400/Bitcoin-Designers-site). To improve the design, please start with the Figma file and make a proposal in Slack or Github before implementing. ## Basic markdown formatting @@ -74,7 +76,7 @@ There should be whitespace between paragraphs. ### Images -Let's start with a very wide image that extends beyond the content with on desktops. Note how a different images is shown on mobile. This can be used to reformat image content to a portrait format. +Let's start with a very wide image that extends beyond the content width on desktops. Note how a different image is shown on mobile. This can be used to reformat image content to a portrait format. {% raw %} ```liquid