ジョブカン事業部のアドベントカレンダー18日目です
よろしくお願いします
何の記事ですか
ドキュメントを書くことに苦手意識を持つ人間が、
どうすればできるだけ楽に早くドキュメントを作成できるか？
について勉強した内容をふんわりまとめたものです。
自己紹介です
ジョブカン事業部 開発エンジニアの@tk1111です
札幌拠点でジョブカン勤怠管理の開発をしています。
過去の投稿からの流れで自分もやりました、 新・RPGジョブ診断。
強みは創造性とインプット力らしいです。
でも今回はアウトプットについての記事です。
ドキュメントを書くのが苦手です。
なぜ書くのが苦手なのか
自分の場合は何から書けばいいかわからないことが多いからです。テーマと要素は大方決まっているのに、書き始めるまでに色々と考えてしまい時間がかかります。なのですぐに書き始められる方法を調べたところ、テクニカルライティングにたどり着きました。
テクニカルライティングを実践すると何がいいのか
テクニカルライティングとは、技術的な情報をわかりやすく正確に書く技術です。わかりやすいドキュメントを短時間で書けるようになるらしいです。
- 書き手がうれしいこと
- 作成する目的に合わせた構成の考え方ができる
- 書く場所と内容が明確になる
- 時短になる
- 読み手がうれしいこと
- 欲しい情報を見つけやすい
- 伝えたい内容が理解しやすい
- 時短になる
最高ですね。ということで以降はテクニカルライティングの手法に倣って、ドキュメントを作成する時のポイントを書いていきます。
ここから本題 ドキュメントを作成する時のポイント
以降は作成の各ステップについてポイントを記載します。
- 準備
- 読み手を絞る
- テーマを絞る
- アウトライン作成
- 構成要素から文章の流れを作成する
- アウトラインに沿って書く
- パラグラフについて
- 階層構造を作る
- 文章単体で気にすること
準備 書き始める前に何をするか
まず、誰に何を理解してもらうためのドキュメントを作成するのか考えます。
- 読み手が何を知るためにドキュメントを読むのか？
- 記載内容に対して読み手はどの程度の事前知識をもつのか？
読み手とその目的が明確になれば、ドキュメントのテーマを絞っていくことができます。
この記事であれば、想定読者は主にドキュメント作成が得意ではないと思っている技術者の皆さんで、伝えたい内容は今までより少しドキュメント作成を早く楽に書くためのポイントです。
アウトライン作成
大きくテーマが決まったら、アウトラインを作成します。
自分の場合は、まずテーマについて書くべき内容を羅列してから小さく分解します。分解した要素を、目次を作成するつもりで並び替えて整理します。
アウトラインの参考として、学術論文が非常にわかりやすい例だと思います。
学術論文は基本的に対象読者が同分野の研究者で、伝えたいことは自身の研究成果についてですね。
要約
ここを読めば大まかに全てを理解できるように論文の全体をまとめます。一番難しいです。
背景
なぜその研究をしたのか、研究によって解決すべき問題などを書くところです。
研究内容
以下の流れで、問題解決のために実施したことを書きます。
- 仮説
- 実験内容
- 結果
結論
研究内容の項目で実施したこと、得られた結果をまとめて論文の意義を書きます。
メソッド
実験内容について、手法と材料などを記載します。ここを読めば読者が実験を再現できるように書く必要があります。
上記のような構成になっており、目的に応じてどこを読めば良いか一目瞭然です。研究分野による文化の違いがあったらすみません。
英語が得意でない読者が英語の論文を読んでも、その分野の専門的なワードを知っていれば内容を把握できるように書かれています。
実際のアウトラインは作成するドキュメントの目的によって変わります。しかし作成するドキュメントの属性が何であれ、伝えたい内容を分解して似た要素のまとまりを整理することで伝える順序を作りやすくなります。
アウトラインに沿って書く
ドキュメントに書く項目と流れが決まったら、各項目に内容を当てはめていきます。
パラグラフ
パラグラフ(段落)は、1つの大きな内容についての複数の文章のまとまりです。
研究論文の例でいうと、背景や仮説が1つのパラグラフになります。
1つのパラグラフには1つの内容についての記述のみを行います。最初の1文を読めば言いたいことを理解できるように書きます。そうすると、最初の一文がタイトルや見出しの機能を持ちます。
2文目以降は、最初の文を説明したり、補足する内容を書いていきます。
階層構造を作る
大きく同じ内容についてのパラグラフを複数まとめることで、読み手に内容のまとまりを把握してもらうことができます。
研究論文の例でいうと、研究内容は、1つの研究についてのパラグラフが集合して階層構造を作っています。1本の論文内に複数の研究結果があった場合、各内容についてまとめます。
- 研究1
- 研究1についての仮説
- 研究1についての実験
- 研究1についての結果
- 研究2
- 研究2についての仮説
- 研究2についての実験
- 研究2についての結果
この階層構造を構成することによって、どのような流れで研究が進んでいったのかを説明している形です。
文章単体で気にすること
パラグラフを構成する文章単体について書き方を意識することで、理解しやすい・読みやすい文章を作成します。
以下に意識するといいことを記載します。
用語・表現を統一する
ドキュメント内で出てくる用語や表現について、同じ意味のものは全て同じ言葉で書きます。
一文を短くする
端的に表現して、文章を整理する負荷を与えないようにします。
- 例：
現在日程調整中になりますので、決まりましたら関係者に報告いたします。 - 修正：
現在日程調整中です。決まりましたら関係者に報告いたします。
二重否定を使わない
目的を達成するためには何をすればいいのか？を理解しやすいように書きます。
- 例：
レビュアー2名のapproveがないとPRをマージできません。 - 修正：
レビュアー2名のapproveがあるとPRをマージできます。
ドキュメントの目的を意識する
同じ内容であっても、何のための文章なのか？によって書き方が変わります。
- 手順書の場合：
コミットをプッシュすると、対象ブランチに対して自動テストが実行されます。 - 機能説明の場合：
コミットがプッシュされると、対象ブランチに対して自動テストを実行します。
曖昧にしない
どうすればよいのか？を確実に伝えるために明確な言葉で表現します。
- 肯定文で書く
- 断定する
上記の内容は一例であり、突き詰めていくと無限に出てくると思うので一旦これくらいで勘弁してください。
パラグラフや文章単体についての項目は、アウトライン作成などよりも慣れが必要でないため、頭に入れておくだけで効果があるものだと思います。
おわりに
ここまで読んでくださりありがとうございます。
この記事では、書き物が苦手な人が楽に早く書くときの考え方をドキュメント作成の流れに沿ってまとめました。
書いた本人はというと、この記事に書いていることの全てを意識しながら実践するのは難しいので、簡単に取り入れられそうなものや実践することで作業が楽になりそうなものから練習しているところです。
修正すべき点は多くあると思いますが、少しでも書き物が苦手な人の助けになれば幸いです。
自分は書き始めるのに一番時間が必要なんですが、書いてる最中はそれなりに楽しんでやれています。楽しみすぎて脱線したくなる気持ちを抑えながら書きました。
これまで勉強したこととはいえ、実際に記事にしてみると出来るだけ間違ったことを書かないように慎重になるので更に勉強になりますね。
今回こういった記事を初めて書きましたが、技術系の記事も書いてみたいと思いました。
参考文献
エンジニアが一生困らないドキュメント作成の基本 (仲田 尚央)
テクニカルライティングについて検索すると参考ページがたくさん出てきますが、自分は調べていく中でより興味が出たため、↑の書籍を読みました。実践しやすく書かれていて参考になります。
仲間を大募集中です
株式会社DONUTSでは、新卒中途を問わず積極的に採用活動を行っています
自社プロダクトの開発で腕を奮いたい方、顧客への価値提供にやりがいを感じたい方、ぜひご応募ください
ジョブカン事業部の開発エンジニア募集はこちらです。
自分の所属する札幌オフィスは、3年前（執筆当時）に設立した新しい開発拠点です。
一緒に新拠点を盛り上げてくれる仲間を募集しています