diff --git a/README.md b/README.md index f5a7aa2..1a7e4eb 100644 --- a/README.md +++ b/README.md @@ -6,17 +6,3 @@ It's built using [Docusaurus](https://docusaurus.io/). It also contains a written guide for contributing to Consensys docs, and creating, configuring, and testing new doc sites, published at [`docs-template.consensys.net`](https://docs-template.consensys.net/). - -## Linting - -Vale is a work in progress (WIP) for linting: `.github/workflows/lint.yml` uses actions set up on -Consensys/docs-gha/lint@main. - -WIP: That GHA repo should be set up to apply the [Vale linting set](https://github.com/ConsenSys/docs-gha/tree/main/spelling). - -### Let's Upset Vale - -The title should do it, so should: - -- Metamask -- ConsenSys diff --git a/docs/contribute/style-guide.md b/docs/contribute/style-guide.md index 3408a14..07d2e95 100644 --- a/docs/contribute/style-guide.md +++ b/docs/contribute/style-guide.md @@ -8,12 +8,12 @@ sidebar_position: 2 Style guidelines help keep the Consensys documentation consistent, concise, and readable. Refer to the following guides when writing, editing, or reviewing doc content: -- [**Microsoft Writing Style Guide**](https://learn.microsoft.com/en-us/style-guide/welcome/) - - Refer to this guide for style, voice, grammar, and text formatting guidelines. +- [**Microsoft Writing Style Guide**](https://learn.microsoft.com/en-us/style-guide/welcome/) - Refer to this guide for style, voice, grammar, and text formatting guidelines. - [**Diátaxis framework**](https://diataxis.fr/) - Refer to this guide for information about function-based docs. -- [**Consensys Editorial Style Guide**](https://docs.google.com/document/d/1smRdw4TUIpz9re_o0_0DKdH_nK6cSPMJOK6BcbhjJ7Y/edit?usp=sharing) - +- [**Consensys Editorial Style Guide**](https://www.notion.so/consensys/Consensys-Editorial-Style-Guide-d5b9867e85df4ae38f8bed44f61a77d5) - Refer to this guide for spelling and usage of blockchain-related terms. + [Vale](run-vale.md) assists writers to adhere to this style. This guide is only available to internal Consensys contributors. The following section also highlights the top five style tips from these guides. @@ -54,7 +54,7 @@ in your writing: :::info example -❌ *If we are unable to find another library that works with the execution environment, another way +❌ *If we're unable to find another library that works with the execution environment, another way of solving the problem is by patching the dependency ourselves. For this, `patch-package` can be leveraged.* @@ -69,10 +69,10 @@ Write for a [developer audience](https://learn.microsoft.com/en-us/style-guide/d - You don't need to market the product to the reader. Understand what they're seeking to learn or do, and optimize your content to help them achieve - that quickly. + that fast. - List prerequisites and suggest good practices. For example, instruct readers to secure private keys and protect RPC endpoints in production environments. -- Write [code samples](format-markdown.md#code-sample-style-guide) that are readable, can be easily +- Write [code samples](format-markdown.md#code-sample-style-guide) that are readable, can be copied and pasted, and work as expected. :::info example @@ -152,7 +152,7 @@ elements](https://learn.microsoft.com/en-us/style-guide/text-formatting/): ❌ *[Click here](https://discord.gg/hyperledger) for Besu support.* -✅ *If you have questions about Besu for public networks, ask on the **besu** channel on -[Hyperledger Discord](https://discord.gg/hyperledger).* +✅ *If you have questions about Besu for public networks, ask on the **#besu** channel on +[LFDT Discord](https://discord.gg/hyperledger).* :::