コントリビュータのためのスタイルガイド

対象読者: ドキュメントの作成者と編集者

このスタイルガイドでは、reStructuredText (RSTとも呼ばれます) を使用したベストプラクティスも参照しますが、 一般的には、広く受け入れられているドキュメント標準であるMarkdownでドキュメントを書くことをお勧めします。 ただし、どちらの形式も使用可能です。 RSTでトピックを作成することにした場合 (またはRSTで書かれたトピックを編集する場合) は、必ずこのスタイルガイドを参照してください。

疑問がある場合は、フォーマットに関する手引きとしてドキュメントそのものを使用する

• RSTフォーマット

• Markdownフォーマット

フォーマットの方法を確認したいだけなら、ページ右上隅の Edit on GitHub リンクをクリックしてFabricリポジトリに移動し、次に Raw タブをクリックします。これにより、ドキュメントのフォーマットが表示されます。 GitHub上でファイルを編集しないでください。 もし、ファイルに変更を加えたい場合には、リポジトリをクローンし、そして Contributing のプルリクエストの作成方法に従ってください。

言葉の選び方

「ホワイトリスト (whitelist) 」「ブラックリスト (blacklist) 」「マスター (master) 」「スレーブ (slave) 」などの単語の使用は避ける

これらの単語の使用が絶対に必要でない限り (例えば、これらの単語を使用しているコードのセクションを引用する場合)、これらの単語を使用しないでください。 その単語をより明確にする (例えば、「ホワイトリスト化 (whitelisting) 」が実際に何をするものなのかを説明する) か、「許可リスト (allowlist) 」や「ブロックリスト (blocklist) 」のような代替語を見つけるかしてください。

チュートリアルでは、ページのトップにステップのリストが必要

チュートリアルの冒頭にステップのリスト (対応するセクションへのリンク付き) があると、ユーザーは興味のある特定のステップを見つけるのに役立ちます。例えば、 Use private data in Fabric を確認してください。

「Fabric」、「Hyperledger Fabric」それとも「HLF」？

最初は「Hyperledger Fabric」と記述し、その後は「Fabric」とのみ記述すべきです。「HLF」は使用しないでください。また、「Hyperledger」は単独では使わないでください。

Chaincode (単数形) vs. Chaincodes (複数形) ？(英語表記の場合)

1つのチェーンコードを表す場合、単数形の「chaincode」を使用してください。 複数のチェーンコードについて話している場合は、複数形の「chaincodes」を使用してください。

スマートコントラクト？

口語的には、スマートコントラクトはチェーンコードと同等と見なされますが、技術的なレベルでは、「スマートコントラクト」はチェーンコードの内部のビジネスロジックであり、より大きなパッケージと実装を内包していると言ったほうが正しいでしょう。

JSON vs. json ？

「JSON」を使用してください。他のあらゆるファイル形式（例えば、YAML）も同様です。

curl vs cURL

このツールは「cURL」と呼ばれています。コマンド自体は「curl」コマンドです。

Fabric CA

「fabric-CA」、「fabricCA」、または「FabricCA」とは呼ばないでください。 正しくは「Fabric CA」です。 ただし、Fabric CAのクライアントバイナリは fabric-ca-client と呼ぶことができます。

Raft と RAFT

「Raft」は頭文字をとった略語 (acronym: 頭字語) ではありません。 そのため、「RAFTオーダリングサービス」と呼ばないでください。

読者の参照の仕方

「あなた (you) 」や「私たち (we) 」を使うのはまったく問題ありません。 「私 (I) 」の使用は避けてください。

アンパサンド (&)

「and」という単語の代わりにはなりません。それを使用する理由がない限り (例えば、それを含むコードスニペットなど)、使用を避けてください。

頭字語 (Acronyms: 頭文字をとった略語のこと)

ある頭字語を最初に使う場合には、それが広く使用されていない限り、スペルアウトする必要があります。例えば、最初の使用時には「Software Development Kit (SDK: ソフトウェア開発キット) 」、 その後は「SDK」を使用します。

同じ単語を頻繁に使用しない

1つの文で同じ単語を2回使用するのを避けることができるなら、そうしてください。1つの段落内でも2回以上使用しないほうがよいでしょう。もちろん、これを避けることができない場合もあります。--- 使用されているステートデータベースに関するドキュメントは、「データベース」または「台帳」という単語の使用でいっぱいになる可能性があります。しかし、特定の単語を過剰に使うと、読者を麻痺させてしまう傾向があります。

ファイル名はどのようにつけるべきか？

単語の区切りにはアンダースコアを使う。また、チュートリアルにはそれがわかる名前を付けるべきです。例えば、 identity_use_case_tutorial.md といった具合です。すべてのファイルがこの標準を使用しているわけではありませんが、新しいファイルはこの標準に従うべきです。

フォーマットと句読点

行の長さ

ドキュメントの生ファイルを見ると、多くのトピックが約70文字 (70 characters) の行長に準拠していることがわかります。この制限はもはや必要ありませんので、自由に好きなだけ行を長くすることができます。

太字にするタイミング

それほど頻繁ではありません。それらの最良の使用法は、要約として、または話したい概念に注意を引く方法として、のどちらかです。 「ブロックチェーンネットワークには台帳、少なくとも1つのチェーンコード、そしてピアが含まれています」というように、特にその段落の中でそれらのことについて話そうとしているのであればなおさらです。 「ブロックチェーンネットワークは適切なセキュリティプロトコルを使用する 必要がある (原文: Blockchain networks must use proper security protocols) 」などのように、1つの単語を強調するためだけに太字を使用することはできません。

バッククォート nnn で囲むタイミング

これは、プレーンな英語では意味を成さない単語や、コードの一部を参照する際 (特に、コードスニペットをドキュメントに入れている場合) に注意を引くのに便利です。 例えば、 fabric-samples ディレクトリについて話すときは、fabric-samples のようにバッククォートで囲みます。 hf.Revoker のようなコード関数も同様です。また、コードのコンテキストで参照している場合には、コードの一部であるプレーンな英語で意味のある単語をバッククォートで囲むのも意味があるかもしれません。 例えば、アクセス制御リストの一部として attribute を参照している場合です。

ダッシュを使用することは適切か？ (英語表記の場合)

ダッシュは非常に便利ですが、個別の宣言文を使用するよりも技術的に適切であるとは限りません。以下の例文を考えてみましょう。

これにより、トリミングされたJSONオブジェクトが残ります --- config.json、これはfirst-network内のfabric-samplesフォルダにあります --- 設定更新のベースラインとして機能します

原文:
This leaves us with a trimmed down JSON object --- config.json, located in the fabric-samples folder inside first-network --- which will serve as the baseline for our config update.

同じ情報を提示するにはいくつかの方法がありますが、この場合ではダッシュを使うことで、同じ考えの一部として情報を保持しつつ、情報を分断しています。 ダッシュを使用する場合は、ハイフンの3倍の長さの「em」ダッシュを必ず使用してください。これらのダッシュの前後にはスペースが必要です。

ハイフンを使うタイミング (英語表記の場合)

ハイフンは主に「複合形容詞」の一部としてよく使用されます。たとえば、「jet-powered car」などです。 複合形容詞は、修飾される名詞の直前になければならないことに注意してください。言い換えると、「jet powered」自体はハイフンを必要としません。 複合形容詞は厄介で、文法の掲示板でもよく議論されているので、疑問がある場合はGoogleで検索して下さい。

ピリオドの後のスペースは何個？ (英語表記の場合)

1つです。

数値はどのように記述するべきか？ (英語表記の場合)

0から9までの数字は単語で綴っています (one, two, three, four etc.)。10以降の数字は数字として記述されます。

例外として、コードからの使用があります。その場合は、コードの中にあるものを何でも使ってください。また、Org1のような例もあります。 OrgOneとして記述しないでください。

ドキュメントタイトルの大文字使用ルール (英語表記の場合)

文中の大文字の使用に関する標準ルールに従う必要があります。 つまり、単語がタイトルまたは固有名詞の最初の単語でない限り、最初の文字を大文字にしないでください。 例えば、「Understanding Identities in Fabric」は「Understanding identities in Fabric」である必要があります。 すべてのドキュメントがこの標準に準拠しているわけではありませんが、これは私たちが移行しようとしている標準であり、新しいトピックでは従う必要があります。

トピック内の見出しも、同じ標準に従う必要があります。

オックスフォード・カンマ (Oxford comma) を使用するか? (英語表記の場合)

はい、それがよりよいです。

典型的な例は、「I’d like to thank my parents, Ayn Rand and God.」よりも「I’d like to thank my parents, Ayn Rand, and God.」がよいです。

図表のキャプション (Captions)

図表のキャプションはイタリック体である必要があり、私たちのドキュメントではイタリック体の唯一の有効な使用法です。

コマンド

一般的には、それぞれのコマンドをそれぞれのスニペットに入れます。特にコマンドが長い場合は、その方が読みやすいでしょう。このルールの例外は、いくつかの環境変数のエクスポートを提案する場合です。

コードスニペット

Markdownでは、サンプルコードを記載する場合は、3連のバッククォートを使用してスニペットを開始します。例えば、以下のようになります。

ここにコードが入ります。

さらに多くのコードがここに入ります。

さらに多くのコードが続きます。

RSTでは、次のようなフォーマットを使用してコードスニペットを開始する必要があります。

.. code:: bash

   ここにコードが入ります。

必要に応じて、JavaやGoなどの言語で bash を置き換えることができます。

Markdown内の番号付きリスト (Enumerated list)

Markdownでは、リストアイテムを空行で区切った場合、番号付きリストは機能しないことに注意してください。 Markdownはこれを古いリストの継続ではなく、新しいリストの始まりと見なします（すべての数字は 1. になります）。 番号付きリストが必要な場合は、RSTを使用する必要があります。 箇条書きリスト (Bulleted list) は、Markdownの優れた代替品であり、推奨される代替手段です。

リンク

他のドキュメントにリンクする場合は、直接リンクではなく相対リンクを使用してください。 リンクに名前を付けるときは、単に「link」のように名付けないでください。よりクリエイティブで説明的な名前を使用してください。 アクセシビリティ上の理由から、リンク名はリンクであることを明確にするべきです。

すべてのドキュメントの最後にはライセンス文が必要

RSTでは以下の通りです。

.. Licensed under Creative Commons Attribution 4.0 International License
   https://creativecommons.org/licenses/by/4.0/

Markdownでは以下の通りです。

<!--- Licensed under Creative Commons Attribution 4.0 International License
https://creativecommons.org/licenses/by/4.0/ -->

インデントのためのスペースは何個か？

これはユースケースに依存します。 多くの場合、特にRSTでは、特にコードブロックで2つのスペースをインデントする必要があります。 RSTの .. note :: ボックスでは、次のように、note の後のコロンの後のスペースをインデントする必要があります。

.. note:: いくつかの単語や文章などなど (行は70文字の制限行まで続く)
          直下の行は上の行と同じスペースから始めなければならない。

どのタイプの見出しをいつ使用するか

RSTでは、以下を使用します。

チャプター (Chapter) 1 タイトル
===============================

セクション (Section) 1.1 タイトル
---------------------------------

サブセクション (Subsection) 1.1.1 タイトル
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

セクション (Section) 1.2 タイトル
---------------------------------

タイトルの下にある記号 (=-~) の長さは、タイトル自体の長さと同じでなければならないことに注意してください。 これはデフォルトで各文字に同じ幅を与えているAtomでは問題ではありません (Jeopardyを使用していて、その情報が必要な場合は、これは「モノスペース (monospacing) 」と呼ばれます)。

Markdownでは、それはやや単純です。

# ドキュメントの名前 (これは目次 (TOC) のために引っ張られます)

## 1つ目のサブセクション (Subsection)

## 2つ目のサブセクション (Subsection)

どちらのファイルフォーマットも、これらが順不同で行われることを好みません。例えば、# タイトルの後に最初に #### が欲しいかもしれません。しかし、Markdownはそれを許可しません。 同様に、RSTはあなたがタイトルフォーマットに与えた順序をデフォルトにします (ドキュメントの最初のセクションに表示されます)。

可能な場合は相対リンクを使用する

RSTの場合、推奨される構文は次のとおりです。 :doc:`アンカーテキスト <相対パス>` ファイルパスの最後には .rst 接尾語を付けないでください。

Markdownの場合、推奨される構文は次のとおりです。 [アンカーテキスト](<相対パス>)

テキストファイルやYAMLファイルなどの他のファイルの場合は、GitHub内ファイルへの直接リンクを使用します。以下に例を示します。

https://github.com/hyperledger/fabric/blob/master/docs/README.md

GitHub上でRSTファイルをブラウジングする場合、残念ながら相対リンクは機能しません。