Fastifyスタイルガイド
はじめに
Fastifyスタイルガイドへようこそ。このガイドは、オープンソースフレームワークであるFastifyの開発者ドキュメントを作成するユーザーに、標準的な記述スタイルを提供することを目的としています。各トピックは正確かつ分かりやすく説明されており、ユーザーが理解しやすく実装しやすいドキュメントを作成するのに役立ちます。
このガイドの対象者
このガイドは、Fastifyで開発するのが好きな方、またはドキュメントに貢献したい方のためのものです。技術ドキュメントの作成経験は問いません。このガイドが皆様のお役に立てれば幸いです。
ウェブサイトの貢献するページをご覧いただくか、GitHubのCONTRIBUTING.mdファイルを読んで、オープンソースコミュニティに参加してください。
記述の前に
以下の知識が必要です
- JavaScript
- Node.js
- Git
- GitHub
- Markdown
- HTTP
- NPM
読者を考慮する
記述を始める前に、読者を考えてください。この場合、読者はすでにHTTP、JavaScript、NPM、Node.jsの知識を持っていると想定されます。読者はコンテンツを利用する人々であるため、常に読者を念頭に置いておく必要があります。できる限り有益な情報を提供することを心がけてください。読者が知っておくべき重要な事柄と、それらをどのように理解できるかを考えてください。読者が容易に理解できる言葉や参考文献を使用してください。コミュニティからフィードバックを求めることで、ユーザーと目標に焦点を当てた、より良いドキュメントを作成するのに役立ちます。
要点を絞る
読者が取るべき明確かつ具体的な行動を示してください。最も重要なことから始めてください。こうすることで、読者は必要な情報をより早く見つけることができます。多くの場合、読者はページの最初のコンテンツを読み、それ以上スクロールしない傾向があります。
例
避けるべき例: コロンはパラメトリックパスを登録するために非常に重要です。コロンを使うことで、フレームワークは新しいパラメータが作成されたことを認識します。パラメータ名の前にコロンを配置することで、パラメトリックパスを作成できます。
推奨される例: パラメトリックパスを登録するには、パラメータ名の前にコロンを付けます。コロンを使用することで、フレームワークはそれが静的パスではなくパラメトリックパスであることを認識します。
動画や画像コンテンツの追加は避ける
ドキュメントに動画やスクリーンショットを追加しないでください。バージョン管理が容易になります。新しいアップデートが開発されるにつれて、動画や画像は最終的に古くなってしまいます。代わりに、参照リンクまたはYouTube動画を作成してください。Markdownで`[タイトル](www.websitename.com)`を使用してリンクを追加できます。
例
To learn more about hooks, see [Fastify hooks](https://fastify.dokyumento.jp/docs/latest/Reference/Hooks/).
結果
フックの詳細については、Fastifyフックを参照してください。
盗作を避ける
他人の著作物をコピーしないようにしてください。できる限りオリジナルのものを心がけてください。他人の著作物から特定の引用を使用した場合は、その内容を学び、出典を明記することができます。
言葉遣い
ドキュメントを読みやすくし、ドキュメントを整理し、直接的で分かりやすくするために、記述時に使用すべき言葉遣いと避けるべき言葉遣いがいくつかあります。
二人称「あなた」を代名詞として使用する場合
記事やガイドを記述する場合、コンテンツは読者に対して二人称（「あなた」）で直接語りかけるように記述する必要があります。特定のトピックについて、読者に直接指示を与える方が簡単です。例については、プラグインガイドを参照してください。
例
避けるべき例: 次のプラグインを使用できます。
推奨される例: 次のプラグインを使用することができます。
Wikipediaによると、**_あなた_**は通常、二人称代名詞です。また、非常に形式ばった不定代名詞の代わりに、不特定の人物を指す場合にも使用されます。
二人称「あなた」を代名詞として使用しない場合
リファレンスドキュメントやAPIドキュメントなどの正式な文章を書く際の主なルールの1つは、二人称（「あなた」）を使用したり、読者に直接語りかけたりすることを避けることです。
例
避けるべき例: 次の推奨事項を例として使用できます。
推奨される例: 例として、次の推奨事項を参照してください。
実際の例については、デコレータリファレンスドキュメントを参照してください。
短縮形を使用しない
短縮形とは、単語の書かれた形式と話し言葉の形式を短くしたものです。たとえば、「do not」の代わりに「don't」を使用することです。よりフォーマルなトーンにするために、短縮形は避けましょう。
見下すような言葉遣いを避ける
見下すような言葉遣いには、次のような言葉が含まれます。
- ただ
- 簡単
- 単純に
- 基本的に
- 明らかに
読者がFastifyのフレームワークやプラグインを使いにくいと感じるかもしれません。単純、簡単、攻撃的、または無神経に聞こえる言葉は避けましょう。ドキュメントを読むすべての人が同じレベルの理解を持っているわけではありません。
動詞で始める
多くの場合、説明は動詞で始めると、読者が理解しやすくなります。過去形や未来形よりも現在形の方が読みやすく理解しやすいので、現在形を使用することをお勧めします。
例
避けるべき例: Fastifyを使用するには、Node.jsをインストールする必要があります。
推奨される例: Fastifyを使用するには、Node.jsをインストールしてください。
法
法（mood）は、文章を表現するための優れた方法です。直接的な表現をしながらも、命令口調にならないようにしましょう。直説法、命令法、仮定法をいつ切り替えるかを知っておく必要があります。
**直説法** - 事実の記述や質問をするときに使用します。
例: 利用可能なテストフレームワークがないため、「Fastifyはテストの記述方法を推奨しています」。
**命令法** - 指示、行動、命令を与えたり、見出しを記述したりするときに使用します。
例: 開発を開始する前に、依存関係をインストールしてください。
**仮定法** - 提案、仮説、または事実ではない記述をするときに使用します。
例: フレームワークの包括的な知識を得るためには、ウェブサイトのドキュメントを読むことをお勧めします。
**受動態**の代わりに**能動態**を使用する
能動態を使用すると、ドキュメントをより簡潔かつ直接的に伝えることができます。
例
受動態: ノードの依存関係とパッケージは、npmによってインストールされます。
能動態: npmはパッケージとノードの依存関係をインストールします。
記述スタイル
ドキュメントのタイトル
`/docs/`ディレクトリに新しいガイド、API、またはリファレンスを作成する場合は、ドキュメントのトピックを最もよく表す短いタイトルを使用してください。ファイル名はケバブケースで命名し、Rawケースやキャメルケースは避けましょう。ケバブケースの詳細については、ケーススタイルに関するMediumの記事を参照してください。
例:
hook-and-plugins.md,
adding-test-plugins.md,
removing-requests.md.
ハイパーリンク
ハイパーリンクには、参照先の明確なタイトルを付ける必要があります。ハイパーリンクの記述方法は次のとおりです。
<!-- More like this -->
// Add clear & brief description
[Fastify Plugins] (https://fastify.dokyumento.jp/docs/latest/Plugins/)
<!--Less like this -->
// incomplete description
[Fastify] (https://fastify.dokyumento.jp/docs/latest/Plugins/)
// Adding title in link brackets
[](https://fastify.dokyumento.jp/docs/latest/Plugins/ "fastify plugin")
// Empty title
[](https://fastify.dokyumento.jp/docs/latest/Plugins/)
// Adding links localhost URLs instead of using code strings (``)
[http://localhost:3000/](http://localhost:3000/)
ドキュメントには、できるだけ多くの重要な参考文献を含める必要がありますが、初心者のためのドキュメントを作成する場合は、注意散漫にならないようにリンクの数を少なくしてください。