Zenn
🙌

効率的な知識共有に適したテンプレートの考案：技術記事と引継ぎ資料の効果的な作成方法

2024/02/27に公開
2件
#
テンプレート
#
フォーマット
#
技術文書
#
情報共有
#
文書作法
tech

1. 概要

  1. 本記事は，技術ブログ / 引き継ぎ書 に適したテンプレートを検討
  2. 技術ブログ / 引き継ぎ書 は，各人がそれぞれの書き方で作成することが多い
  3. そのため，以下の問題があると考察
    • 書き手においては，何を書けば良いかわからず多大な労力を要する
    • 読み手においては，多くの文書から所望の文書を探すのが困難
  4. 課題解決のため，技術ブログ / 引き継ぎ書 における以下記載の テンプレート を考案
考案した技術文書/引継ぎ資料のテンプレート
# 1. 概要

# 2. 序論
## 2.1. 背景
## 2.2. 対象読者 / 適用範囲
## 2.3. 目的
## 2.4. 仮定 / 環境
## 2.5. 略語 / 用語
## 2.6. キーワード

# 3. 課題
## 3.1. 現状（Situation，雲）
## 3.2. 理由付け（Complication，雨）
## 3.3. 解決法（Resolution，傘）

# 4. 先行事例 / 具体例

# 5. 本題

# 6. 結論
## 6.1. まとめ
## 6.2. 展望
## 6.3. その他

# 7. 参考文献

2. 序論

2.1. 対象読者 / 適用範囲

  • 技術記事 / 引継ぎ資料 をコスパ・タイパよく作成したい人
  • 読みやすい資料を作成したい人
  • 研究室の大学生・大学院生（後輩向け）
  • 技術記事 / 引継ぎ資料 作成時

2.2. 目的

  1. 各種資料から，フォーマット/テンプレートを纏める
  2. 書き手・読み手に優しいテンプレートを考案する

2.3. 仮定 / 環境

  • SEOについては考慮していない（参考文献 [1]を挙げる）
  • ブログおよびWord等の文書作成ツールで作成する文書を想定

2.4. 略語 / 用語

2.4.1. 略語

N/A

2.4.2. 用語

  • テンプレート：特定の文書やデータの構造や形式を指定するための具体的な枠組み
  • フォーマット：文書の全体的なレイアウトや構造を指します
    （フォーマットはテンプレートに含まれる）

2.5. キーワード

  • テンプレート
  • フォーマット
  • 資料作成

3. 資料作成の課題

3.1. 資料作成時（Situation）

  • 基本的に，先輩→後輩のように，知識を持っている人が持っていない人に向けて作成
  • 書き手は読み手を指定できない
  • ロステクを防ぐために資料作成するが，特に引継ぎ資料などは時間を取れない
  • 書き手はある程度の知識を持っていて，詳しいほど詳細な説明をしてしまう

3.2. 作成時の悩み（Complication)

  • 前提知識が異なるとその文書自体が理解できない
  • 全員に対応する文書を作成しようと思うと，内容が膨大になる
  • 文書作成において，見出し（文書構成，章節項）の決定が，作業量の大半を占める
  • 執筆時点で，読み手のニーズは分かりえない
  • 詳細に説明しようとすると，本のようになってしまうため，書き手も読み手も大変

3.3. 解決法（Resolution）

  • 以下を持つフォーマット / テンプレートを作成
    • 文書の適用範囲を明示：読み手が，読むか否かを判断．書き手はスコープ絞れて楽．
    • 目的：文書の動機付け（モチベーション）
    • 課題：読み手が，内容についての気持ち（その分野の常識的なもの）を知る
    • 先行事例（や具体例）：イメージしやすくなる
    • 本題
    • 参考文献：適用文書でも可．主題以外は積極的に他の資料の説明に委ねたい
  • 適用文書を明らかにした上で，資料を分割（細分化）

4. フォーマット / テンプレートの事例

先行事例を確認したいと思います．いずれも非常に纏まっていて使いやすいものです．

4.1. 計画書・報告書

JAXAの共通文書 [2] から試験計画書に記述すべき事項は以下の通りとの記載がある．

  • 適用範囲
  • 適用文書
  • 試験目的
  • 試験対象品目
  • 試験実施場所
  • スケジュール
  • 実施体制
  • 試験内容（試験項目、条件、フロー等）
  • 試験コンフィギュレーション
  • 周囲環境条件（試験時、保管時及び輸送時の環境）
  • 試験装置、設備及び計測方法
  • 安全管理
  • 信頼性管理

所感として，計画書に最低限書くことが纏まっていて，非常に使いやすいものである．
過去使っていて良いと思った点は，適用範囲 が書かれていることである．これによって，この文書を読むべきか否かを判断できることがとても役立った．
また，適用文書についてもこの位置にあることで，資料間の繋がりを意識することが出来て，資料が作りやすくなるという旨味もある．

4.2. サーベイ論文の書き方の手順

記事や参考文献も基本手には情報の寄せ集めになると思う．情報が集まっていて有益であったものと言えば，私にとってサーベイ論文であった．研究ではサーベイ論文には非常にお世話になった．その分野のロードマップ的なものとして読むことが出来，情報を纏める際には役立つものである．そんなサーベイ論文の書き方について纏まっている文書[3]は以下を提案している．

  1. Title
  2. Abstract
  3. Introduction
  4. Literature with benefits and limitations
  5. Result analysis
  6. Conclusion
  7. Future Research Direction
  8. References

この文書構成もとても良いが，その中でも，有益さと制限を纏めるというところが非常に重要だと考えている．これにより文書を読む際に頭に入りやすくなるし，その分野の常識のようなものも手に入る（ロードマップ的な要素）．
よって，JAXAの文書では適用範囲を記載することで文書のスコープを狭めたが，さらに先行事例をbenefitsとlimitationsなどを添えて纏めることで，文書の理解をしやすくなると考える．

4.3. SCR：課題のまとめ方

おそらく大体の記事や文書は，何らかの課題を解決するものだと思われる．体系的に纏まっている専門書でも，課題などを示したうえで解決法を提示するという手法が多くみられる．また，読み手においては課題があるため，解決法を探しているという人が多いように思われる．
そんな時にフレームワークが役に立つと考えている．日本で有名な，雲雨傘の論理 というものがある．コンサルの本によく出てくるものであるが，元々はMcKinseyのSCR Fremeworkだと思う．よく参考にしている文献 [4][5] からSCRについて以下のように記載されている．

  • Situation
    The framing of the important, recent context the audience already knows and accepts as fact.
  • Complication
    The reason the situation requires action.
  • Resolution
    The action required to solve a problem (or capture an opportunity).

私の理解が不十分かもしれませんが，三角ロジックと同じだと思います．ここで重要なのが，主張（Resolution）と事実（Situation）が読み手にとって関係性の分かりにくいものであると，主張が理解できなくなってしまいます．事実は認められるが，主張は認められないということになります．そうならないように，理由付け（Complication)によって円滑に事実から主張を導く　必要があります．この理由付け（Complication）の役割を果たすものこそ，課題なのだと思っています．
少し分かりにくい文書になりましたが，

  1. 課題を分かり易く説明することで読み手は主張を理解しやすくなる
  2. 課題を説明する手法として，SCR（雲雨傘）が良い
    と考える．
    よって，本記事のようにSCRを用いて課題を説明し，そのまま主題への導入を行う．

4.4. PREP：論理的文書を書くための定番フレームワーク

4章で紹介してきたフォーマットを用いて，文書の大きな枠組みはほとんど決定された．あとは，本題の部分を分かり易くするフォーマットを考える必要がある．資料における分かり易い文書というのは，論理的な文書であると思われる．いくら平易な文であっても，論理の飛躍があれば理解できず分からないからである．そこで，使えるであろうフレームワークは，PREP法である．

  • Point：要点や結論を先に言う
  • Reason：理由付け
  • Example：具体例を出す
  • Point：再度，要点や結論を言う

PREP法を使ってきて，Exampleを上手く言えないと理解されないということがあった．これは少し異なるかもしれないが，参考書などで練習問題を解くことでさらに理解が深まる現象と同じであると考えている．よって，本題のパートでは，理由付けをするだけでなく，具体例まで出すと良いのではないかと考える．

4.5. 質問テンプレート

過去Twitter等で流行った質問テンプレートについて考える．テンプレートの概要は，

  • 実現したいこと・やりたいこと
  • 実行したこと・やったこと
  • 結果
  • 想定していた結果

です．私が好きな数学ガールや数学文章作法を書いている結城先生のメルマガにあるテンプレート[6] の内容を抽出したものとなっています．
　なぜ，質問テンプレートについて考えたかというと，読み手は疑問を持って文書を読んでいるからである．しかし，読み手が自分の疑問を正しく理解（言語化）できているとは限らない．つまり，無知の無知 の状態であるかもしれない（自分もそうなることがあるので）．　
よって，書き手がそもそもこの質問テンプレートのように自分の無知を知る（分かっていないところを明確にする）フォーマットで文章を書けば，それだけで 技術記事 / 引継ぎ資料 としては十分に機能しているのかもしれない．

4.6. 特許明細書のフォーマット

特許の電子出願ソフトサポートサイトの資料 [7] にも，発明の概要 には以下の項目が挙げられている．

  • 【発明の概要】
  • 【発明が解決しようとする課題】
  • 【課題を解決するための手段】
  • 【発明の効果】

特許明細書の目的は，特許事務所のHP　[8] より，

明細書には、大きく分けて、公的立場から、研究の成果としての発明の内容を正確かつ明瞭に第三者に公開するための技術文献という役割と、私的な立場から、特許権として主張すべき技術的範囲を明らかにする権利書としての役割があります。

技術記事においても内容を正確かつ明瞭に共有するということ点から，同様の目的を持っていると言える．そのため，考案しようとするフォーマットにおいて，課題と解決する手段を挙げて，その手段の効果を示すという手法は，特許という技術文献としても使われている，効果的なものであると言える．

4.7. その他フォーマット

以下の資料[9]が分かり易かった．技術記事には，トライ系・紹介系・レポート系 の3種類があるとして，それぞれのテンプレートを提示している．
https://zenn.dev/renn/articles/454ea916a29236

その他の議事録などのフォーマットなどは，以下の文献をいつも参考にしている．非常に有用なサイトである．この中のビジネス文書の章を参考にした．
https://yutakatay.gitbook.io/katapedia/doc/dokyumento

5. 考案するテンプレート

伝えたいことは，HWやSW，試験方法や専門知識など様々です．可能な限り汎用的に使用できるテンプレートを作成したい．

5.1. テンプレート本体

今回考えたテンプレート例を以下に示す．

1. 概要

2. 序論
2.1. 背景
2.2. 対象読者 / 適用範囲
2.3. 目的
2.4. 仮定 / 環境
2.5. 略語 / 用語
2.6. キーワード

3. 課題
3.1. 現状（Situation，雲）
3.2. 理由付け（Complication，雨）
3.3. 解決法（Resolution，傘）

4. 先行事例 / 具体例

5. 本題

6. 結論
6.1. まとめ
6.2. 展望
6.3. その他

7. 参考文献

5.2. テンプレートについての説明

さて，それぞれの項目について説明する．
なお，すべての事柄において，
該当するモノがない場合は，N/A （Not Applicable（該当なし））
未定である場合は，TBD （To Be Determined）
と記載する．
つまり，すべての項目をすべて埋める必要はなく，適宜サボる．
各項目においても，出来るだけ手を抜けるように頑張ると書き手は楽になる．
ここで，未決定事項や非該当であれば削除する方がいいと思うかもしれないが，読み手が 記載がないモノは不要なモノである と示すのはとても大変である．
同一フォーマットを使用している文書群において，省略されている章節項が間違って削除されたのかを判断するなどを読み手が判断するのはそれなりに労力を要する．
この方針は，自分の経験的なところから来るものなので，各自の判断に委ねる．

最初は，概要です．

1. 概要
記事すべてを簡単にまとめる．動画でいうダイジェスト的なモノ．Abstract．

次に，序論です．ここを見て，読み手は 読むか否かを判断 ，書き手は 内容のスコープ を絞れる．

2. 序論
記事や文書の導入部分としての役割．技術記事としては，興味を引く部分．

2.1. 背景
背景知識を述べる。

2.2. 対象読者 / 適用範囲
人の属性 or　対象のイベントでスコープを絞ります．
どちらでも絞りたい場合は，項を用意して，
2.2.1. 対象読者
Ex. 目的は見つかっていないが，pythonを始めたい人
2.2.2. 適用範囲
Ex. 高校物理，帝京大学での熱真空試験
とするとよいかもしれません．
俗にいう，ペルソナ設定． 

2.3. 目的
本文書のゴールを設定します．
サクセスクライテリアでも可能．読み手も読みやすくなる．

2.4. 仮定 / 環境
留意点的な内容をここに書く．
ここで，読み手と書き手の齟齬を防ぐ．
数学や物理であれば，ここに仮定を書く．Ex. 衛星は円軌道を周回する
ソフトウェアなどであれば，開発環境など．Ex. Windows11, pytnon3.10.1

2.5. 略語 / 用語
用語集があると読み手に易しいし，齟齬を防げる．
特に初学者などの分野の知識が少ない人においては，
用語は一般的な用語なのか判断できず理解できないこともしばしば．

例えば，ADCという単語があったとき，
Attitude Detemination and Control
Analog to Degital Converter
など同じ略語でも複数の単語が存在するため，明示するために記載．
Ex. SAM : Serviceable Available Market
Ex. 姿勢：機体座標系における位置・角度

2.6. キーワード
キーワードで読むか否かを判断することもあるので．
SEOは詳しくないが，メタキーワード的なモノ．
Ex. 技術文書，フォーマット

次は課題についてです．『課題』という名前が少し良くなくて，ここでは 主張 をします．
4.3節でも述べましたが，コンサルなども使うフォーマットを利用します．内容は軽めでいいと思います．内容整理も兼ねています．内容について学ぶ/読むことの動機付けです．
（カスタマージャーニー，ステークホルダーマップなど応用して図を使えるといいかも）

3. 課題
名前を適宜変更してください．読み手の悩みが書いてあればよい．
動機づけをしましょう．その手法によっては独自性が生まれると思います．

3.1. 現状（Situation，雲）
4.3節を参考に．ファクトや数値などを書きます．
Ex. 何もしなければ人工衛星の回転は止まることがない
Ex. 空を見たら暗く黒い雲が西にあった

3.2. 理由付け（Complication，雨）
4.3節を参考に，起こりうる課題（問題）を挙げてください．
ただし，起こりうる課題のうち，文書で提案する解決法で解ける課題を示す．
Ex. 人工衛星の太陽電池が太陽の方向を向いていないと充電不可能
Ex. 黒い雲は，雨降りがち（もう少し丁寧にいってもよい）

3.3. 解決法（Resolution，傘）
文書が提案することを挙げます．
Ex. 人工衛星に姿勢制御器のRWを搭載（そして，RWについて本文で説明）
Ex. 傘を持っていく（そして，傘について本文で説明）

次は，先行事例 / 具体例です．結城先生の数学ガール中での文言で恐縮ですが，『例示は理解の試金石』という言葉が好きで，読み手に配慮するために具体例を示します．
ここも簡単でいいと思います．
先行研究的な使い方で，過去の文書などを挙げるなどしてその主張を記載したうえで，自分の主張に繋げるための文言などを記載する場所．

4. 先行事例 / 具体例
既に似たような記事などはどこかしらにあると思います．
しかし，スコープや解決したい課題などが変われば独自性や新規性が生まれると思います．
ここでは，分かり易い例などを挙げて本文に入るまでの前提知識の擦り合わせを行います．
本記事では，テンプレートの事例について挙げました．

次は，本題です．ここが文書の肝となる部分です．もしかすると，5章だけでなく，6章，7章と章を増やしてもいいかもしれません．本題の後に来るのは，結論と参考文献ですので，章を増やすことによる影響はほとんどありません．読み手もテンプレートの構成的に，結論の前までが本題なのだろうと分かると思います．

5. 本題
本題です．この部分は，書きたい内容によって大きく形が変わると思います．
ここはテンプレートを気にせずに好きに書きたいです．
1章から4章までを記載すれば，書くべき対象はそれなりに絞れられています．
文だけでなく，プログラムコードや数式，フローチャート，ロジックツリーなど様々使用．

次は，結論です．内容としては最後です．言いたいことを纏めます．ただ全てを纏めると概要と同じ内容になるので，主張について特に纏めるとよいと思います．

6. 結論
本章全体で内容を纏めます．締めです．

6.1. まとめ
主張を纏めておきます．サマリー．
基本的には，目的に対応した内容が含まれていればよいと思います．

6.2. 展望
内容を応用できる事柄や発展した内容といった展望を記載．
だいたい書きたいことは2つのパターンがあると思います．
1つ目は，「新しくこんな事が可能になるかも？」といったポジティブな内容
2つ目は，「本文書ではスコープ外としたが，考える必要のある」ネガティブな内容

6.3. その他
主題とは関係ないけど，書いておきたいことなどが少なからずあると思います．
余計なことでも書いておくとよいかもしれません．
最後に配置してあるので，あまり邪魔にはならないと思います．
或いは，Appendix（補足）的な立ち位置でもよいかもしれません．
或いは，謝辞などでもよいかも．

最後に，参考文献です．参考にした文書やリンクなどを挙げておきます．引用などもすると思いますので，zennであれば脚注の機能を使うと良さそうです．参考文献が纏まっているとそれだけでも有難い資料になると思いますので，それを意識して書きたい．

7. 参考文献
脚注などの機能を用いる．文献が使われている部分にリンクが飛んでいると優しい．

ちなみに，『おわりに』などの方が優しい感じがしますが，使う場合は，序論に対して結論，はじめにに対しておわりに，などと対応関係を意識するのが良いと思われる．

6. 結論

6.1. まとめ

技術記事および引継ぎ文書と言った，読み手が何か情報を探し求めていると考えられる文書のテンプレートを作成した．本資料の筆者が常日頃参考にしていた資料について考察し，メリットをテンプレートに落とし込んだ．提案するテンプレートは，全7章に渡り，読み手と書き手の前提知識を出来るだけ擦り合わせた上で本題について知ることが出来るように配慮した．
書き手と読み手のそれぞれのメリットを以下に纏める．

書き手：

  • テンプレートを採用することで，文書作成の手間を軽減
  • 複数文書に渡って一貫した形式を保てる
  • スコープを絞れるため，書くべき内容が分かり易い
  • テンプレートに従うことでニーズに応えることが可能

読み手 :

  • 統一されたフォーマットにより検索性が高まる
  • 自分が読むべき対象なのか判断しやすい
  • 自分が分かっていない点が分かる可能性が高まる
  • 背景知識も含めて知ることが出来る

6.2. 展望

6.2.1. 各項目の名称の命名法

名称を上手く変更することで，目次だけで伝えたい内容を伝えることが出来る．
ここは上手く考えられていない．

6.2.2. 親テンプレートとしての使用法

ここで提案したテンプレートを親テンプレートとして，応用する．
所謂，継承というもの．汎用化したものの，それぞれの分野に特化した使い方というものが存在すると思っている．

6.3. その他

最後にはなりますが，人工衛星開発をしている研究室にいた服部と申します．
修士論文が無事通ったので，後輩に向けての引継ぎ資料を作成しています．
人工衛星という総合工学という分野にいるせいか，引継ぎは多岐な分野に渡るため，分野ごとに伝えたいことを考えて作成しようとしていました．
しかし，なぜか普段のスピードで資料が作成できないという悩みに行きつきました．
その原因を考えていたところ，普段は JAXAの共通文書のフォーマットを利用して試験計画書などを作成していたからでした．
軽く調べたところあまりカチッとしたフォーマットは見つからなかったので，自分でフォーマットを考えてみることにした．
何かの参考になりましたら，幸いです．

何かございましたらこちらまでご連絡ください：hattori.sat[at]gmail.com
[at]を@に変更してください．

2024-02-27 新規作成

参考文献

脚注

  1. Google，”Googleが掲げる10の事実”，https://about.google/philosophy/?hl=ja ↩︎

  2. JAXA，”宇宙機一般試験標準”，https://sma.jaxa.jp/TechDoc/Docs/JAXA-JERG-2-130D.pdf ，2022 ↩︎

  3. ESSAYPRO.com，”How to Write a Survey Paper:Important Steps”，https://essaypro.com/blog/how-to-write-a-survey-paper-brief-overview ↩︎

  4. SpeakingSherpa，”How to Tell a Business Story Using the McKinsey Situation-Complication-Resolution (SCR) Framework”，https://speakingsherpa.com/how-to-tell-a-business-story-using-the-mckinsey-situation-complication-resolution-scr-framework/ ↩︎

  5. Kasper Vardup, Mats Stigzelius，”How to use McKinsey's SCR fremework (with examples”，https://slideworks.io/resources/how-to-use-McKinseys-scr-framework-with-examples ↩︎

  6. 結城浩，”技術系メーリングリストで質問するときのパターン・ランゲージ”，https://www.hyuki.com/writing/techask.html ↩︎

  7. 電子出願ソフトサポートサイト，”【発明の概要】（明細書）”，https://www.pcinfo.jpo.go.jp/guide/Content/Guide/Patent/Meisai/Kyotsu/PHatsumeiGaiyou.htm ↩︎

  8. 坂野国際特許事務所，”特許明細書”，https://www.saka-pat.com/patent-meisaisho.htm ↩︎

  9. れん，”【完全版】世界一見られる技術ブログの書き方【テンプレート有】”，https://zenn.dev/renn/articles/454ea916a29236 ↩︎

GitHubで編集を提案

Discussion

hattori-sathattori-sat

何かアドバイスや改善点，議論したい点があればコメントしていただけますと幸いです．

少し修正．SCRのところが少し理解が難しそう．
なので，どこかで見た以下の書き方は分かり易そう．

問題点1

Ex. 文章作成に時間がかかる

現状

Ex. 書きたいことは多いが，どのように書けば良いか迷っている

解決法

Ex. テンプレートを利用する

hattori-sathattori-sat

テンプレートを使えば文章を簡単に書きやすくなって良いと思うが，内容だけでなくタイトルもかなり重要．記事なのでSEO的なことを考えて，釣りっぽいタイトルを付けたくなるが，論文のようにタイトルだけで内容が分かり易いものを付けれるのが理想．