見出し画像

ドキュメントを作る前に、ガイドラインを作ろう

Koushi Kagawa

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

ガイドラインとは何か​

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

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

ガイドラインの必要性​

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

文書の一貫性​

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

時間短縮​

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

ナレッジの共有​

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

専門分野に対応​

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

誰に向けて作るのか​

ドキュメント作成のためのガイドラインは、作成する組織や団体によって異なります。 一般的には、社内の内部のスタッフ、外部のパートナーや顧客などに向けて作られることが多いです。

経験豊富なメンバーが多い場合、基本的なガイドラインは不要となります。 逆にライティングの知識の少ないメンバーが多い場合は、細かく盛り込む必要があります。 メンバーのスキルセットをもとに、どこまで細かく書くかを選定する必要があります。

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

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

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

原則

チームメンバーがガイドラインの意図を理解できるような原則を盛り込みます。

トーン&マナー

ドキュメントの口調は丁寧語か、そうではないか、親しみやすさを出すか、固めにいくか、などドキュメント全体のマナーを記載します。

ドキュメントの構成

「タイトル」「本文」「見出し」「注意書き」など、ドキュメントの構成要素を記載します。

用語集

ドキュメント内で利用する用語、利用しない用語をまとめます。

連作先

ガイドラインの管理者は誰なのか、困ったときは誰に聞けば良いのか、レポートラインを記載します。

参考文献

参考文献を紹介する場合のフォーマット、参考文献の使い方などを記載します。

ツール利用方法

スクリーンショットを撮影するツールは何か、開発環境の情報など、ドキュメントを利用するにあたり必要なツールの情報を記載します。

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

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

  • 簡単にアクセスできること

  • 作成/更新が容易にできること

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

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

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

常に最新に更新する​

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

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

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

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

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

参考

ガイドライン作成において、参考になる書籍と本を紹介します。​

書籍​

伝わるWebライティング -スタイルと目的をもって共感をあつめる文章を書く方法 > [Chapter 12 スタイルガイドを確立しよう]

日本語スタイルガイド(第3版)

おなじみのこちらの本。自社でガイドラインを制定する工数が取れない場合や、最初はこの本をガイドラインにするのが良いかもしれません。

サイト​

SmartHR Design System
SmartHRさんがまとめているガイドです。特にコンテンツのセクションはライティングに関する情報がまとまっており参考になります。

読んでいただきありがとうございます。