fabric-docs-i18n icon indicating copy to clipboard operation
fabric-docs-i18n copied to clipboard

[ja_JP] Contributions Welcome! / Style guide for contributors

Open shimos opened this issue 2 years ago • 0 comments

Original HTML: https://hyperledger-fabric.readthedocs.io/en/release-2.5/style_guide.html Original Source: https://github.com/hyperledger/fabric/blob/e1e8e2e52aa4fc543360d245fe6554a0eaf81183/docs/source/style_guide.md

diff --git a/docs/source/style_guide.md b/docs/source/style_guide.md
index f65a20886..469f24969 100644
--- a/docs/source/style_guide.md
+++ b/docs/source/style_guide.md
@@ -12,15 +12,28 @@ While this style guide will also refer to best practices using ReStructured Text
 
 If you just want to look at how things are formatted, you can navigate to the Fabric repo to look at the raw file by clicking on `Edit on Github` link in the upper right hand corner of the page. Then click the `Raw` tab. This will show you the formatting of the doc. **Do not attempt to edit the file on Github.** If you want to make a change, clone the repo and follow the instructions in [Contributing](./CONTRIBUTING.html) for creating pull requests.
 
-## Word choices
-
-**Avoid the use of the words "whitelist", "blacklist", "master", or "slave".**
+## Inclusive language
+
+Please adhere to the inclusive language guidelines that the project has adopted as you make documentation updates.
+
+- Consider that users who will read the docs are from different backgrounds and
+cultures and that they have different preferences.
+- Avoid potential offensive terms and, for instance, prefer "allow list and
+deny list" to "white list and black list".
+- We believe that we all have a role to play to improve our world, and even if
+writing inclusive documentation might not look like a huge improvement, it's a
+first step in the right direction.
+- We suggest to refer to
+[Microsoft bias free writing guidelines](https://docs.microsoft.com/en-us/style-guide/bias-free-communication)
+and
+[Google inclusive doc writing guide](https://developers.google.com/style/inclusive-documentation)
+as starting points.
 
-Unless the use of these words is absolutely necessary (for example, when quoting a section of code that uses them), do not use these words. Either be more explicit (for example, describing what "whitelisting" actually does) or find alternate words such as "allowlist" or "blocklist".
+## Word choices
 
 **Tutorials should have a list of steps at the top.**
 
-A list of steps (with links to the corresponding sections) at the beginning of a tutorial helps users find particular steps they're interested in. For an example, check out [Use private data in Fabric](./private-data/private-data.html).
+A list of steps (with links to the corresponding sections) at the beginning of a tutorial helps users find particular steps they're interested in. For an example, check out [Using Private Data in Fabric](./private_data_tutorial.html).
 
 **"Fabric", "Hyperledger Fabric" or "HLF"?**
 
@@ -78,7 +91,7 @@ If you look at the raw versions of the documentation, you will see that many top
 
 **When to bold?**
 
-Not too often. The best use of them is either as a summary or as a way of drawing attention to concepts you want to talk about. “A blockchain network contains a ledger, at least one chaincode, and peers”, especially if you’re going to be talking about those things in that paragraph. Avoid using them simply to emphasize a single word, as in something like "Blockchain networks **must** use propery security protocols".
+Not too often. The best use of them is either as a summary or as a way of drawing attention to concepts you want to talk about. “A blockchain network contains a ledger, at least one chaincode, and peers”, especially if you’re going to be talking about those things in that paragraph. Avoid using them simply to emphasize a single word, as in something like "Blockchain networks **must** use proper security protocols".
 
 **When to surround something in back tics `nnn`?**
 
@@ -231,7 +244,7 @@ Both file formats don't like when these things are done out of order. For exampl
   For other files, such as text or YAML files, use a direct link to the file in
   github for example:
 
-  [https://github.com/hyperledger/fabric/blob/master/docs/README.md](https://github.com/hyperledger/fabric/blob/master/docs/README.md)
+  [https://github.com/hyperledger/fabric/blob/main/docs/README.md](https://github.com/hyperledger/fabric/blob/main/docs/README.md)
 
   Relative links are unfortunately not working on github when browsing through a
   RST file.

shimos avatar Sep 28 '23 01:09 shimos