貢献者ガイド - ドキュメンテーション貢献（Documentation Contributions）

ディスカッション
ドキュメントの種類
ブロックエディターハンドブックプロセス
リソース

ディスカッション

The Make WordPress Docs blogは、WordPressドキュメントに関する最新情報の主要な場所であり、発表、製品目標、会議のメモ、会議の議題などが含まれます。

ドキュメントに関するリアルタイムのディスカッションは、Make WordPress Slackの#docsチャンネルで行われます（登録が必要です）。ドキュメンテーションチームの週次会議は、火曜日の14:00UTCに行われます。

Gutenbergプロジェクトは、コードの管理と問題の追跡にGitHubを使用しています。メインリポジトリは次のとおりです: https://github.com/WordPress/gutenberg。作業するドキュメントの問題を見つけるには、ドキュメントラベルのある問題を参照してください。

ドキュメントの種類

Gutenbergプロジェクトには、2つの主要なドキュメントセットがあります:

1. ユーザードキュメントは、投稿を公開する著者としてエディターを使用する方法に関する情報です。ユーザードキュメントに貢献するには、ドキュメントブログをフォローするか、#docs Slackチャンネルで現在の優先事項を理解するために尋ねてください。
2. ブロックエディターハンドブックは、Gutenbergプロジェクトに関連するすべての情報を含みます: 開発、拡張、そして今読んでいるGutenbergに特有の貢献です。

このドキュメントの残りの部分は、ブロックエディターハンドブックへの貢献について説明します。

ブロックエディターハンドブックプロセス

ブロックエディターハンドブックは、Gutenbergプロジェクトリポジトリの/docs/ディレクトリ内のマークダウンファイルと、パッケージから生成されたドキュメントの組み合わせです。

自動化されたジョブが15分ごとにドキュメントをブロックエディターハンドブックサイトに公開します。

変更をプルリクエストを使用してデプロイする方法については、Gitワークフローのドキュメントを参照してください。さらに、ドキュメントへの貢献のためのビデオウォークスルーとそれに付随するスライドを参照してください。

ハンドブックの構造

ハンドブックは、文書の機能的な種類に基づいて4つのセクションに整理されています。ドキュメンテーションシステムは、各タイプのニーズと機能を説明するのに優れた役割を果たしていますが、簡単に言うと、次のようになります:

はじめにのチュートリアル – 学習者が目標を達成するためにステップバイステップで進む完全なレッスン、例えばブロックを作成するチュートリアル。
ハウツーガイド – 小さな特定のタスクを完了するための短いレッスン、例えばブロックツールバーにボタンを追加する方法。
リファレンスガイド – APIドキュメント、純粋な機能的説明、
説明 – 特定のタスクではなく、学習に焦点を当てた長いドキュメントです。

テンプレート

ハウツーガイドテンプレートが利用可能で、ガイドに共通の構造を提供します。新しいハウツーガイドを開始する場合は、テンプレートからマークダウンをコピーして開始してください。

このテンプレートは、The Good Docs Projectの例に基づいています。質の高いドキュメントを作成するための追加の例については、彼らのテンプレートリポジトリを参照してください。

ドキュメントの更新

既存のページを更新するには:

1. Gutenbergリポジトリをチェックアウトします。
2. 作業用のブランチを作成します。例えばdocs/update-contrib-guide。
3. 既存のドキュメントに必要な変更を加えます。
4. 変更をコミットします。
5. [Type] Developer Documentationラベルを使用してプルリクエストを作成します。

新しいドキュメントの作成

新しいドキュメントを追加するには、ドキュメントを構築するための作業JavaScript開発環境が必要です。詳細については、JavaScriptビルドセットアップドキュメントを参照してください:

1. docsフォルダーにマークダウンファイルを作成します。小文字を使用し、スペースを入れず、必要に応じてダッシュ区切りを使用し、.md拡張子を付けます。
2. マークダウン表記を使用してコンテンツを追加します。すべてのドキュメントには、1つだけh1タグが必要です。
3. toc.json階層にドキュメントエントリを追加します。フォーマットについては既存のエントリを参照してください。
4. npm run docs:buildを実行してmanifest.jsonを更新します。
5. 他の更新されたファイルと一緒にmanifest.jsonをコミットします。

実行を忘れた場合、npm run docs:buildあなたのPRは静的分析チェックに失敗します。manifest.jsonファイルはコミットされていないローカル変更であり、コミットする必要があります。

パッケージの文書化

パッケージのドキュメントは、パッケージのルートにあるREADME.mdファイルの内容を引き出すことによって、ドキュメントツールによって自動的に生成されます。ただし、READMEの内容を小さく、読みやすい部分に分割する方が望ましい場合があります。

これは、パッケージ内にdocsディレクトリを作成し、toc.jsonファイルを追加して、docsディレクトリ内に含まれる他のマークダウンファイルへの参照を含めることで実現できます。toc.jsonファイルには、メインREADMEファイルのサブページとして追加されるページの配列が含まれている必要があります。フォーマットは、自動的に生成されるmanifest.jsonファイルに従います。

これらのページがメインパッケージ名の下にネストされるようにするには、parentプロパティを正しく設定してください。以下の例では、@wordpress/create-blockセクションに子ページを追加しています。

[
   {
   "title": "@wordpress/create-block External Template",
   "slug": "packages-create-block-external-template",
   "markdown_source": "../packages/create-block/docs/external-template.md",
   "parent": "packages-create-block"
   }
]

リンクの使用

おそらく、どこかの時点で他の内部ドキュメントページにリンクしたくなるでしょう。すべてのドキュメントは異なるコンテキストでブラウズできることを強調する価値があります:

ブロックエディターハンドブック
GitHubウェブサイト
npmウェブサイト

すべてのコンテキストで機能するリンクを作成するには、https://github.com/WordPress/gutenbergプレフィックスなしで絶対パスリンクを使用する必要があります。次のパターンを使用してファイルを参照できます:

/docs/*.md
/packages/*/README.md
/packages/components/src/**/README.md

このようにして、前述の3つのコンテキストですべて適切に処理されます。

Gutenbergリポジトリからの完全なディレクトリとファイル名を使用し、公開されたパスではなく、ブロックエディターハンドブックは短いURLを作成します。これはチュートリアルセクションで確認できます。同様に、readme.md部分はハンドブックでは省略されますが、リンクには含める必要があります。

例として、このページへのリンクは: /docs/contributors/documentation/README.md

注意: 通常のリンク変換は、コールアウト内のリンクには適用されません。以下を参照してください。

コード例

マークダウン内のコード例は、3つのバックティック```で囲む必要があり、言語指定子も含める必要があります。このGitHubのフェンス付きコードブロックに関するドキュメントを参照してください。

Gutenbergドキュメントのユニークな機能は、codetabsトグルで、これにより2つのコードバージョンを同時に表示できます。これは、JSXとPlainのコードサンプルの両方を表示するために使用されます。

以下はcodetabsセクションの例です:

\{\% codetabs \%\}
   \{\% JSX \%\}
   // JSX code here
   \{\% Plain \%\}
   // Plain code here
   \{\% end \%\}

コード例の推奨フォーマットはJSXです。これがデフォルトビューになります。ソース内で最初に配置された例がデフォルトとして表示されます。

注意: すべてのガイドに対してプレーンJavaScriptコード例を含める必要はありません。初心者向けのチュートリアルや短い例にはプレーンコードを含めることを推奨しますが、Gutenbergパッケージやより大きなReactおよびJavaScriptエコシステムの大部分のコードは、ビルドプロセスを必要とするJSXで記述されています。

コールアウト通知

ブロックエディターハンドブックは、他のWordPressハンドブックと同じ通知スタイルをサポートしています。ただし、ブロックエディターハンドブックのドキュメントが公開される異なる場所（npm、GitHub）では、ショートコードの実装が理想的ではありません。

マークダウンでの推奨される実装方法は、生のHTMLとcallout callout-LEVELクラスを使用することです。例えば:

<div class="callout callout-info">This is an **info** callout.</div>

次のクラスが利用可能です: info, tip, alert, warning

これはヒントコールアウトです。

これは情報コールアウトです。

これは警告コールアウトです。

注意: コールアウト通知内のリンクもHTML \u0026lt;a href \\u0026gt;\u0026lt;/a \\u0026gt;表記が必要です。

通常のリンク変換は、コールアウト内のリンクには適用されません。

例えば、Getting started \u0026gt; Create Blockページに到達するには、GitHubのURLは

https://developer.wordpress.org/docs/getting-started/devenv/get-started-with-create-block.md

そして、ブロックエディターハンドブックのエンドポイントに対してハードコーディングする必要があります。

https://developer.wordpress.org/block-editor/getting-started/create-block/がハンドブック内で正しくリンクされるために必要です。

エディタ設定

エディタを設定して、Prettierを使用してマークダウン文書を自動フォーマットする必要があります。完全な詳細については、Getting Startedドキュメントを参照してください。

Visual Studio CodeとPrettier拡張機能を使用するための例の設定:

"[[markdown]]": {
   "editor.defaultFormatter": "esbenp.prettier-vscode",
   "editor.formatOnSave": true
},

このドキュメントを表示している場所によっては、ブラケットが二重に表示される場合があります。正しい形式は単一のブラケットです。

ビデオ埋め込み

ブロックエディターハンドブックのビデオは、WordPress YouTubeチャンネルに非公開ビデオとしてホストする必要があります。このプロセスには追加の権限が必要です。支援が必要な場合は、#marketing Slackチャンネルで連絡してください。

ビデオがYouTubeにアップロードされたら、ビデオ埋め込みリンクを取得します。リンクは次のようになります:

https://www.youtube.com/embed/nrut8SfXA44?si=YxvmHmAoYx-BDCog

次に、ドキュメント内でビデオを埋め込む場所に次のコードを配置します。埋め込みリンクとビデオタイトルを適宜更新してください。

<iframe width="960" height="540" src="[Video embed link]" title="[Video title]" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen="true"></iframe>

ビデオは16:9のアスペクト比を持ち、可能な限り高い解像度で撮影されるべきです。

リソース

コピーガイドラインは、Gutenbergプロジェクトへの指示、ドキュメント、またはその他の貢献を書くためのものです。
トーンと声のガイドは、WordPressドキュメントからのものです。