メインコンテンツまでスキップ

ガイドラインを作ろう

ドキュメントサイトを運用するにあたり、必要になるのがガイドラインです。

ガイドラインとは何か​

ガイドラインとは、ドキュメント作成のための手助けとなるガイドブックのことです。 主に、ドドキュメント作成において適切なフォーマットやスタイル、書き方などを指導するための方針やルールが記載されます。

ガイドラインがあることで、文書作成において適切なフォーマットやスタイル、書き方などの指針を立てることができます。

ガイドラインの必要性​

ガイドラインを用意することで、以下のことに役に立ちます。

文書の一貫性​

ガイドラインに従って作成された文書は、スタイルや書式が統一されます。 そのため、読者にとって読みやすく、信頼性の高い文書になります。 例えば、「1人」と書くのか「一人」と書くのか、日本語としてはどちらも正解です。しかしながら、どちらか１つに統一することで、ドキュメント作成者/読み手を助けることができます。

時間短縮​

ライティング中に、『「1人」と書くのか「一人」と書くのか』で迷ってしまった時に、ガイドラインがあればすぐに解決します。 一方、ガイドラインがない場合は、人に相談する時間がかかります。また、正解案がドキュメント作成者/相談者で決まってしまい、決定した理由が曖昧になってしまいます。

ナレッジの共有​

あなたがライティングしていて困ってしまうことは、他のライターも困っている可能性があります。ガイドラインで制定することにより、多くの人の困ったを解決できます。

専門分野に対応​

特定の分野や目的に対しては、専門的な用語や書式が必要になります。それらに対応したガイドラインがあることで、知識が少ないライターであっても、専門分野において適切な文書が作成できます。

誰に向けて作るのか​

ドキュメント作成のためのガイドラインは、作成する組織や団体によって異なります。 一般的には、組織や団体の内部のスタッフ、外部のパートナーや顧客などに向けて作られることが多いです。 経験豊富なメンバーが多い場合、基本的なガイドラインは不要となります。 逆にライティングの知識の少ないメンバーが多い場合は、細かく盛り込む必要があります。 メンバーのスキルセットをもとに、どこまで細かく書くかを選定する必要があります。

ガイドラインには何を書くのか​

ドキュメント作成において適切なフォーマットやスタイル、書き方などを指導するための情報を記載することが望ましいです。

具体的には、以下のような項目があると良いです。

  • 原則
    • チームメンバーがガイドラインの意図を理解できるような原則を盛り込む
  • トーン&マナー
    • ドキュメントの口調は丁寧語か、そうではないか、親しみやすさを出すか、などドキュメント全体のマナーを記載する
  • ドキュメントの構成
    • 「タイトル」「本文」「見出し」「注意書き」など、ドキュメントの構成要素を記載する。
  • 用語集
    • ドキュメント内で利用する用語、利用しない用語をまとめる
  • 連絡先
    • ガイドラインの管理者は誰なのか、困ったときは誰に聞けば良いのか、レポートラインを記載する
  • 参考文献
    • 参考文献を紹介する場合のフォーマット、参考文献の使い方など、参考文献についてのガイドライン
  • ツール利用方法
    • スクリーンショットを撮影するツールは何か、開発環境の情報など、ドキュメントを利用するにあたり必要なツールの情報を記載する

ガイドラインはどこに書くのが良いか​

NotionやWikiなど、ドキュメントを保管するルールは様々あります。 下記2つが大切なので、これらを満たせるツールをおすすめします。

  • 簡単にアクセスできること
  • 作成/更新が容易にできること

例えば、サポートやセールスなどの非エンジニア向けであればNotionやConfluenceなどのドキュメント管理系ツール、エンジニア中心であればGitHubで文書管理するのも良いでしょう。ご自身の環境に合ったツールを探してみてください。

ガイドライン運用時の注意点​

最後に、ガイドライン運用時の注意点をまとめます。

常に最新に更新する​

ガイドラインは重要なコミュニケーションツールです。常に最新になるように心がけましょう。 １ヶ月に1度は見直し、最新に更新する癖をつける必要があります。

あくまで指針として利用する​

ガイドラインは必ず守らなくてはいけないものではありません。 あくまで方向性を示すものであって、ガイドラインに則った結果読みにくくなってはいけません。 絶対的なものではないので、常に何が正しいのかを議論し、更新して言ってください。

みんなで利用し、改善する​

せっかく作ったので、チームメンバーに周知し利用してもらいましょう。

参考​

図書​

サイト​