From d418965085b07030e50d969ec2a951d5b43eb713 Mon Sep 17 00:00:00 2001 From: umi-umi <57262844+umi-umi@users.noreply.github.com> Date: Wed, 24 Jun 2020 06:32:42 +0900 Subject: [PATCH 1/3] add documentation_best_practices.md translation --- docs/ja/documentation_best_practices.md | 69 +++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 docs/ja/documentation_best_practices.md diff --git a/docs/ja/documentation_best_practices.md b/docs/ja/documentation_best_practices.md new file mode 100644 index 000000000000..ed23e3e4ab79 --- /dev/null +++ b/docs/ja/documentation_best_practices.md @@ -0,0 +1,69 @@ +# ドキュメントベストプラクティス + + + +このページは QMK のためのドキュメントを作成する時のベストプラクティスを文章化するために存在します。これらのガイドラインに従うことで、一貫したトーンとスタイルを維持することに役立ちます。これは他の人が QMK をより簡単に理解するのに役立ちます。 + +# ページの開始 + +ドキュメントページは通常 H1 ヘッダから始まり、ユーザがこのページで見つける内容の一段落の説明が続く必要があります。この見出しと段落は目次の次にあるため、見出しを短くして、空白の無い長い文字列を避けるように気を付けてください。 + +例: + +``` +# My Page Title + +This page covers my super cool feature. You can use this feature to make coffee, squeeze fresh oj, and have an egg mcmuffin and hashbrowns delivered from your local macca's by drone. +``` + +# 見出し + +通常、ページには複数の "H1" 見出しが必要です。目次には H1 と H2 見出しのみが含まれるため、適切に計画してください。目次が広くなりすぎないように、H1 と H2 の見出しでは幅を広げないようにしてください。 + +# スタイル付きのヒントボックス + +注目を集めるためにテキストの周囲にスタイル付きのヒントボックスを描画することができます。 + +### Important + +``` +!> This is important +``` + +以下のように描画されます: + +!> This is important + +### 一般的なヒント + +``` +?> This is a helpful tip. +``` + +以下のように描画されます: + +?> This is a helpful tip. + + +# 文章化機能 + +QMK のために新しい機能を作成した場合、そのドキュメントページを作成してください。長い必要は無く、機能を説明する幾つかの文と、関連するキーコードをリストした表で十分です。以下は基本的なテンプレートです: + +```markdown +# My Cool Feature + +This page describes my cool feature. You can use my cool feature to make coffee and order cream and sugar to be delivered via drone. + +## My Cool Feature Keycodes + +|Long Name|Short Name|Description| +|---------|----------|-----------| +|KC_COFFEE||Make Coffee| +|KC_CREAM||Order Cream| +|KC_SUGAR||Order Sugar| +``` + +ドキュメントを `docs/feature_.md` に配置し、そのファイルを `docs/_sidebar.md` の適切な場所に追加します。キーコードを追加した場合は、機能ページに戻るリンクとともに `docs/keycodes.md` に追加するようにしてください。 From 34a43b6849ba1fe6111cce3bbaf0f0d4c9dda61a Mon Sep 17 00:00:00 2001 From: umi-umi <57262844+umi-umi@users.noreply.github.com> Date: Thu, 25 Jun 2020 18:40:40 +0900 Subject: [PATCH 2/3] update based on comment --- docs/ja/documentation_best_practices.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/ja/documentation_best_practices.md b/docs/ja/documentation_best_practices.md index ed23e3e4ab79..47b5bf80f397 100644 --- a/docs/ja/documentation_best_practices.md +++ b/docs/ja/documentation_best_practices.md @@ -5,11 +5,11 @@ git diff 0.9.19 HEAD -- docs/documentation_best_practices.md | cat --> -このページは QMK のためのドキュメントを作成する時のベストプラクティスを文章化するために存在します。これらのガイドラインに従うことで、一貫したトーンとスタイルを維持することに役立ちます。これは他の人が QMK をより簡単に理解するのに役立ちます。 +このページは QMK のためのドキュメントを作成する時のベストプラクティスを文章化するためのものです。これらのガイドラインに従うことで、一貫したトーンとスタイルを維持することでき、他の人が QMK をより理解しやすくすることができます。 # ページの開始 -ドキュメントページは通常 H1 ヘッダから始まり、ユーザがこのページで見つける内容の一段落の説明が続く必要があります。この見出しと段落は目次の次にあるため、見出しを短くして、空白の無い長い文字列を避けるように気を付けてください。 +ドキュメントページは通常 H1 ヘッダで始まり、最初の段落を使ってこのページの内容を説明します。この見出しと段落は目次の次にあるため、見出しは短くして空白の無い長い文字列を避けるように気を付けてください。 例: @@ -21,19 +21,19 @@ This page covers my super cool feature. You can use this feature to make coffee, # 見出し -通常、ページには複数の "H1" 見出しが必要です。目次には H1 と H2 見出しのみが含まれるため、適切に計画してください。目次が広くなりすぎないように、H1 と H2 の見出しでは幅を広げないようにしてください。 +通常、ページには複数の "H1" 見出しが有るべきです。H1 と H2 見出しのみが目次に含まれるので、適切に計画してください。目次が広くなりすぎないように、H1 と H2 の見出しでは幅を広げないようにしてください。 -# スタイル付きのヒントボックス +# スタイル付きのヒントブロック -注目を集めるためにテキストの周囲にスタイル付きのヒントボックスを描画することができます。 +注意を引くためにテキストの周りにスタイル付きのヒントブロックを描くことができます。 -### Important +### 重要なもの ``` !> This is important ``` -以下のように描画されます: +以下のように表示されます: !> This is important @@ -43,14 +43,14 @@ This page covers my super cool feature. You can use this feature to make coffee, ?> This is a helpful tip. ``` -以下のように描画されます: +以下のように表示されます: ?> This is a helpful tip. -# 文章化機能 +# 機能を文章化する -QMK のために新しい機能を作成した場合、そのドキュメントページを作成してください。長い必要は無く、機能を説明する幾つかの文と、関連するキーコードをリストした表で十分です。以下は基本的なテンプレートです: +QMK のために新しい機能を作成した場合、そのドキュメントページを作成してください。長い必要は無く、機能を説明する幾つかの文と、関連するキーコードを列挙した表で十分です。以下は基本的なテンプレートです: ```markdown # My Cool Feature @@ -66,4 +66,4 @@ This page describes my cool feature. You can use my cool feature to make coffee |KC_SUGAR||Order Sugar| ``` -ドキュメントを `docs/feature_.md` に配置し、そのファイルを `docs/_sidebar.md` の適切な場所に追加します。キーコードを追加した場合は、機能ページに戻るリンクとともに `docs/keycodes.md` に追加するようにしてください。 +`ドキュメントを `docs/feature_.md` に配置し、そのファイルを `docs/_summary.md` の適切な場所に追加します。キーコードを追加した場合は、機能ページに戻るリンクとともに `docs/keycodes.md` に追加するようにしてください。 From d5916b70b67048517520fe7708f9dfb8283b1167 Mon Sep 17 00:00:00 2001 From: umi-umi <57262844+umi-umi@users.noreply.github.com> Date: Fri, 26 Jun 2020 18:43:21 +0900 Subject: [PATCH 3/3] update based on comment --- docs/ja/documentation_best_practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ja/documentation_best_practices.md b/docs/ja/documentation_best_practices.md index 47b5bf80f397..50ec4ea6afe0 100644 --- a/docs/ja/documentation_best_practices.md +++ b/docs/ja/documentation_best_practices.md @@ -66,4 +66,4 @@ This page describes my cool feature. You can use my cool feature to make coffee |KC_SUGAR||Order Sugar| ``` -`ドキュメントを `docs/feature_.md` に配置し、そのファイルを `docs/_summary.md` の適切な場所に追加します。キーコードを追加した場合は、機能ページに戻るリンクとともに `docs/keycodes.md` に追加するようにしてください。 +ドキュメントを `docs/feature_.md` に配置し、そのファイルを `docs/_summary.md` の適切な場所に追加します。キーコードを追加した場合は、機能ページに戻るリンクとともに `docs/keycodes.md` に追加するようにしてください。