Nette Documentation Preview

syntax 
ドキュメントへの貢献
**********

.[perex]
ドキュメントへの貢献はもっとも価値ある活動のひとつです。ほかの人がフレームワークを理解する助けになるからです。


どう書くか
-----

ドキュメントは主に、その話題にはじめて触れる人のためのものです。ですからいくつかの大事な点を満たすべきです。

- 単純で一般的な考え方から始めます。より進んだ話題へ進むのは最後にします。
- できるだけ分かりやすく説明するよう努めます。たとえば、まず同僚に説明してみてください。
- その話題で利用者が本当に必要とする情報だけを書きます。
- 書いた情報が正しいかを確かめます。すべてのコードを試してください。
- 簡潔にします。書いたものを半分に削ってください。そしてもう一度やっても構いません。
- 強調は控えめに使います。太字から `.[note]` のような囲みまで同じです。
- コードの例では[コーディング規約|coding-standard]に従ってください。

[記法 |syntax]も学んでください。書きながら記事を下見するには、[プレビューエディタ |https://editor.nette.org/]を使えます。


言語版
---

英語が主の言語なので、変更は英語であるのが理想です。英語が得意でないなら [DeepL 翻訳 |https://www.deepl.com/translator]を使ってください。ほかの人が文を見直します。

ほかの言語への翻訳は、あなたの変更が受け入れられて確定したあとに自動的に行われます。


ごく小さな修正
-------

ドキュメントに貢献するには、[GitHub |https://github.com]のアカウントが要ります。

ドキュメントに小さな変更を加えるいちばん簡単な方法は、各ページの終わりのリンクを使うことです。

- *Show on GitHub* は GitHub でそのページのもとの版を開きます。あとは `E` のキーを押せば編集を始められます（GitHub にログインしている必要があります）。
- *Open preview* はエディタを開き、最終的な見た目をすぐに確かめられます。

[プレビューエディタ |https://editor.nette.org/]は変更を GitHub へ直接保存できないので、編集を終えたら（*Copy to clipboard* のボタンで）もとの文をクリップボードにコピーし、GitHub のエディタへ貼り付ける必要があります。編集の欄の下には送信のフォームがあります。ここに、あなたの修正の理由を手短にまとめて説明するのを忘れないでください。送信すると pull request（PR）が作られ、そのあとも編集できます。


大きめの修正
------

GitHub の画面だけに頼るより、Git のバージョン管理システムの基本を身につけておくほうがよいでしょう。Git に馴染みがないなら、[git - the simple guide |https://rogerdudler.github.io/git-guide/]を見て、たくさんある[図の操作のクライアント |https://git-scm.com/downloads/guis]のどれかを使うことを考えてみてください。

ドキュメントは次のように編集します。

1) GitHub で [fork |https://help.github.com/en/github/getting-started-with-github/fork-a-repo]を作ります。[nette/docs |https://github.com/nette/docs]のリポジトリのものです。
2) そのリポジトリを自分のコンピュータへ [clone |https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository]します。
3) そして[ふさわしいブランチ |#ドキュメントの構造]で変更を加えます。
4) [Code-Checker |tools:code-checker]の道具で、文に余計な空白がないかを確かめます。
5) 変更を保存（コミット）します。
6) 変更に満足したら、それを GitHub の自分の fork へ push します。
7) そこから [pull request|https://help.github.com/articles/creating-a-pull-request]（PR）を作って `nette/docs` のリポジトリへ送ります。

提案のコメントを受け取るのはよくあることです。提案された変更を追いかけて取り入れてください。提案された変更は新しいコミットとして足し、GitHub へまた push します。既存の pull request を直すためだけに、新しい pull request を作っては決していけません。


ドキュメントの構造
---------

ドキュメント全体は GitHub の [nette/docs |https://github.com/nette/docs]のリポジトリにあります。今の版は `master` のブランチに、古い版は `doc-3.x`、`doc-2.x` のようなブランチにあります。

それぞれのブランチの中身は、ドキュメントの領域ごとの主なフォルダに分かれています。たとえば `application/` は `https://doc.nette.org/en/application` に、`latte/` は `https://latte.nette.org` に対応します。これらのフォルダにはそれぞれ、言語版を表す下位のフォルダ（`cs`、`en` など）と、必要なら、ドキュメントのページに差し込める画像の入った `files` の下位のフォルダがあります。

ドキュメントへの貢献

ドキュメントへの貢献はもっとも価値ある活動のひとつです。ほかの人がフレームワークを理解する助けになるからです。

どう書くか

ドキュメントは主に、その話題にはじめて触れる人のためのものです。ですからいくつかの大事な点を満たすべきです。

  • 単純で一般的な考え方から始めます。より進んだ話題へ進むのは最後にします。
  • できるだけ分かりやすく説明するよう努めます。たとえば、まず同僚に説明してみてください。
  • その話題で利用者が本当に必要とする情報だけを書きます。
  • 書いた情報が正しいかを確かめます。すべてのコードを試してください。
  • 簡潔にします。書いたものを半分に削ってください。そしてもう一度やっても構いません。
  • 強調は控えめに使います。太字から .[note] のような囲みまで同じです。
  • コードの例ではコーディング規約に従ってください。

記法も学んでください。書きながら記事を下見するには、プレビューエディタを使えます。

言語版

英語が主の言語なので、変更は英語であるのが理想です。英語が得意でないなら DeepL 翻訳を使ってください。ほかの人が文を見直します。

ほかの言語への翻訳は、あなたの変更が受け入れられて確定したあとに自動的に行われます。

ごく小さな修正

ドキュメントに貢献するには、GitHubのアカウントが要ります。

ドキュメントに小さな変更を加えるいちばん簡単な方法は、各ページの終わりのリンクを使うことです。

  • Show on GitHub は GitHub でそのページのもとの版を開きます。あとは E のキーを押せば編集を始められます（GitHub にログインしている必要があります）。
  • Open preview はエディタを開き、最終的な見た目をすぐに確かめられます。

プレビューエディタは変更を GitHub へ直接保存できないので、編集を終えたら（*Copy to clipboard* のボタンで）もとの文をクリップボードにコピーし、GitHub のエディタへ貼り付ける必要があります。編集の欄の下には送信のフォームがあります。ここに、あなたの修正の理由を手短にまとめて説明するのを忘れないでください。送信すると pull request（PR）が作られ、そのあとも編集できます。

大きめの修正

GitHub の画面だけに頼るより、Git のバージョン管理システムの基本を身につけておくほうがよいでしょう。Git に馴染みがないなら、git – the simple guideを見て、たくさんある図の操作のクライアントのどれかを使うことを考えてみてください。

ドキュメントは次のように編集します。

  1. GitHub で forkを作ります。nette/docsのリポジトリのものです。
  2. そのリポジトリを自分のコンピュータへ cloneします。
  3. そしてふさわしいブランチで変更を加えます。
  4. Code-Checkerの道具で、文に余計な空白がないかを確かめます。
  5. 変更を保存（コミット）します。
  6. 変更に満足したら、それを GitHub の自分の fork へ push します。
  7. そこから pull request（PR）を作って nette/docs のリポジトリへ送ります。

提案のコメントを受け取るのはよくあることです。提案された変更を追いかけて取り入れてください。提案された変更は新しいコミットとして足し、GitHub へまた push します。既存の pull request を直すためだけに、新しい pull request を作っては決していけません。

ドキュメントの構造

ドキュメント全体は GitHub の nette/docsのリポジトリにあります。今の版は master のブランチに、古い版は doc-3.x、doc-2.x のようなブランチにあります。

それぞれのブランチの中身は、ドキュメントの領域ごとの主なフォルダに分かれています。たとえば application/ は https://doc.nette.org/en/application に、latte/ は https://latte.nette.org に対応します。これらのフォルダにはそれぞれ、言語版を表す下位のフォルダ（cs、en など）と、必要なら、ドキュメントのページに差し込める画像の入った files の下位のフォルダがあります。