1. 記述ルール

1.1. ドキュメントの構成

exastro-it-automation-docs
|-- LICENSE
|-- README.md
|-- apple-touch-icon.png
|-- asset                    # 素材ファイルを格納
|   |-- css                  # CSSファイル
|   |-- img                  # 画像素材
|   `-- json                 # コンテンツデータ
|       `-- faq.json         # FAQデータ
|-- documentation
|   |-- Makefile
|   |-- _static
|   |   |-- custom.css
|   |   `-- favicon.ico
|   |-- conf.py
|   |-- exastro_documents
|   |   |-- layout.html
|   |   |-- static
|   |   |   |-- exastro_documents.css
|   |   |   |-- exastro_documents.js
|   |   |   |-- fonts
|   |   |   |-- img
|   |   |   `-- option.css_t
|   |   `-- theme.conf
|   |-- html
|   |   |-- _images
|   |   |-- _sources
|   |   |-- _static
|   |   |-- genindex.html
|   |   |-- index.html
|   |   |-- objects.inv
|   |   |-- search.html
|   |   |-- searchindex.js
|   |   `-- 2.0
|   |       |-- index.html
|   |       |-- ja
|   |       `-- ja_manual_design
|   |-- images
|   |   |-- ja_manual_design
|   |   |   |-- before_after_2_0.png
|   |   |   |-- chart.png
|   |   |   |-- image2.png
|   |   |   |-- indexrst_syntax1_v2_0.png
|   |   |   |-- role_of_index_rst_v2_0.png
|   |   |   |-- sample_img_v2_0.png
|   |   |   |-- title_in_index_rst_v_2_0.png
|   |   |   |-- toctree2_v2_0.png
|   |   |   |-- toctree_lvl1.png
|   |   |   `-- toctree_lvl2.png
|   |   `-- platform
|   |       `-- administrator-console.png
|   |-- index.rst
|   |-- requirements.txt
|   `-- 2.0
|       |-- index.rst
|       `-- ja
|           |-- ansible-driver
|           |-- appendix
|           |-- create_param
|           |-- index.rst
|           |-- installation
|           |-- installation_appendix
|           |-- it_automation_base
|           |-- manual_design
|           |-- platform
|           `-- rest_api
|-- documents.html
|-- documents_ja.html
|-- downloads.html
|-- downloads_ja.html
|-- faq.html
|-- faq_ja.html
|-- favicon.ico
|-- index.html
|-- index_ja.html
|-- learn.html
|-- learn_ja.html
|-- overview.html
|-- overview_ja.html
`-- webinar_ja.html

1.2. 文章の書き方

1.2.1. 目的

ユーザーにとって価値の高い文章を書く方法について記載します。

1.2.2. 前提条件

本項は、

  • ドキュメントを作成する際にどのように表現をすれば良いのかがわからない執筆者

  • ドキュメントのレベルを更に引き上げるため校正者

向けの文章となります。

1.2.3. 概要

ユーザーにとって価値の高い文章とは、最小のコストでユーザーの目的に到達するための手段が明確かつ簡潔に記述された文章です。ユーザーにとって価値の高い文章を書くためには、文章の目的・目標(ゴール)の共有をし、ゴールまでの手段(プロセス)を明確にする必要があります。また、プロセスが発散するのを防ぐために前提(スタート)を設定することも必要です。

1.2.4. 詳細

ユースケースに従うことでわかりやすい文章を書くことができます。
何を目的としてどういったプロセスを実施すれば目的に達成できるのかといった書き方を意識すれば自ずと上記の内容が含まれているはずです。
作りたいもの(目的)があり、調理のそのために必要な材料(前提条件)を準備し、食材を切り、火を通し、味付けをする(概要・詳細)という一連の流れをまとめている、料理のレシピは良いお手本となります。
料理をする上で包丁の刃渡りや鍋の容量はそれほど大きな問題ではなく、本当にユーザーが関心を持っていることは、目的の料理を完成させる方法です。
ユーザーにとって価値の高い文章の構成の具体的な構成は、下記のようになっているべきです。

  1. 目的

  2. 前提条件

  3. 概要

  4. 詳細

  5. 具体例

  6. 付録

「1. 目的」は、読み手(ユーザー)との視点を合わせるために記述するべき内容です。
なぜその操作が必要なのかという理由や、何のための作業なのかといった目的を明確にすることで、ユーザーが同じ視点で文章を読み始めることができるため、よりスムーズに理解ができます。また、探している内容がその文章に含まれているかどうかを判断する材料にもなります。
「2. 前提条件」は、手段を実践するうえで、手段の発散を防ぐために適度に状況を限定するための条件です。
あまり条件をつけすぎると状況が限定されすぎてしまうので、それほど厳格にするべきではありません。
「3. 概要」は、機能を説明する際にそれがどういった目的でどのように利用するものなのかを1文程度で記載した内容です。
ここでは後述の詳細の全体像を理解することを目的としているため、なるべく端的かつ正確に一般論を表現する必要があります。
「4. 詳細」では、利用者が具体的に行う手段について手順レベルでの内容を説明します。
機能の仕様についても併せて記述してもいいですがあまりに細かすぎる情報は却って理解の妨げになるので、「6. 付録」に記載をしてください。また、同様の理由で、本来の利用シーンから逸脱する内容(例外や間違った操作)については、 メモ を活用し文章から除去することで、正常系の操作のみを文章に記載します。
「5. 具体例」では、機能の使い方を説明する際により理解を簡単にするために、具体的な方法について記載します。
「6. 付録」では、主に機能の仕様といった最も詳細なレベルの情報を記載します。

1.2.5. 具体例

本項の構成を参照してください。

1.3. 文体，語句

文体:
ですます体 (体言止めなし)
長音記号有無:
長音は,原則として長音符号「ー」を用いて書く。
※ JIS（日本工業規格）の「Z8301」準拠

1.4. 表記のゆれ

同じ意味をもつ２つ以上の表現は避け、１つに統一します。
e.g.
　ビルド、生成 --> 「ビルド」に統一します。
　できます、出来ます --> 「できます」に統一します。

1.5. ターミノロジー

ターミノロジー（専門用語）を用いる場合は、必ずその意味を最初に説明してから使用します。

1.6. 文法エラー

エディタに付属される構文チェッカーやビルド時に出力結果に Warning や Error が含まれてはいけません。
適切な方法で問題を解消し、文法エラーがない状況でコミットをしてください。