本ブログの趣旨
本ブログでは、技術文書の作成に役立つ知識と手法を解説します。
執筆の経緯
本ブログを執筆するきっかけは、誰にとっても大きな困難となったコロナ禍です。当時の私は、技術文書の作成に関するコンサルティングをしていました。コロナ禍によって予定した案件の中止・延期が相次いで、しばらく途方にくれました。
「このような時にこそ成すべきことがある」と自問する日々が続いた末に、技術文書に関して自身が書きためた内容を体系的にまとめてみようと思い立ちました。始めてみると、書くべき事項が次々と出てきたり幾つもの誤解に気づいたりして、作業のたいへんさに数えきれないほどのため息をつきました。
「わかりやすい技術文書を作成するには何が大切か」が30年間のテーマでした。本ブログの作成を通じて得た答えは、基本の大切さです。1行に満たない文を表すのにも数百ページの文書を構成するのにも基本があります。それを再確認して一つの形にまとめられたことが私にとって最大の収穫になりました。願うのは、本ブログが皆さんの日々の文書作成に役立つことです。
本ブログの読み方
タイトルを開いたページには、当該の項目の「概要」と「目次」が記されています。これらに加えてクラウドに格納された「本文」へのリンクが設定されています。
タイトル-概要・目次-本文(PDFファイル)
・・・ 本文を読む際は、各ページのリンク先をクリックしてください。
【重要】ブログの閲覧およびPDFファイルの表示に伴うトラブルへの責任は、一切負いません。
ブログではタイトルを開いたページに本文を表すのが普通ですが、あえてワープロで作成した本文をPDFファイルにして概要・目次に添付しました。HTML形式ではワープロ文書の表し方を解説しきれないというのがその理由です。
l PDFファイルは、5MB以内です。使用する閲覧ソフトウェアによって表示の細部が若干異なる場合があります。
l PDFファイルの利用は、閲覧のみです。共有やダウンロードなどのご要望には応じかねます。
タイトルの構成
ブログ名を「技術文書の書き方」として大きく広げたからには、見出しの付け方や段落の表し方といった基本から報告書やマニュアルの作り方といった応用までを範囲にしました。
全158タイトル ・・・ 便宜的に20のグループに分けました。各タイトルには、グループ番号が付いています。
グループの順序は、基本から応用に至る構成にしました。序盤のグループ1からグループ10までは、どのような技術文書でも基本となる事項です。
グループ1 見出し構成の考え方、見出し名の付け方 22タイトル
グル―プ2 段落の表し方 8タイトル
グル―プ3 文の表し方-主として単文- 12タイトル
グル―プ4 文の表し方-主として複文- 17タイトル
グル―プ5 名詞修飾の使い方 5タイトル
グル―プ6 箇条書きの使い方 5タイトル
グル―プ7 副本文・注記の使い方 2タイトル
グル―プ8 表の使い方 2タイトル
グル―プ9 図の使い方 3タイトル
グル―プ10 書式の選び方 10タイトル
グループ11からグループ13までは、文を表す際に必要となる実務知識です。特に、グループ11では文の直し方を技術文書で見られる事例を使って解説しました。
グル―プ11 文の直し方 27タイトル
グル―プ12 句読点および記号の使い方 10タイトル
グル―プ13 用字用語の選び方 3タイトル
グループ14からグループ20までは、各種の技術文書の作り方を述べています。中でも、グループ15では企業の報告書で陥りやすい事例を取り上げて、その直し方を解説しました。
グル―プ14 報告書の書き方 7タイトル
グル―プ15 報告書の事例 7タイトル
グル―プ16 各種の文書の表し方-議事録、技術解説- 3タイトル
グル―プ17 取扱いマニュアルの作り方 5タイトル
グル―プ18 システム操作マニュアルの作り方 5タイトル
グル―プ19 ビジネス業務マニュアルの作り方 2タイトル
グル―プ20 作業手順書の作り方 3タイトル
各グループのタイトルも、基本から応用に至る順序で構成しました。
例 9-1 図を使う際の基本 9-2 図の有効な使い方 9-3 図を見やすくする工夫
それぞれが1回で完結する構成であるため、順序にこだわらず関心があるタイトルからお読みになって差し支えありません。ただし、基本を確認するという点では、まずグループ1とグループ2の閲覧を推奨します。
l 各タイトルの内容は、随時に変更・修正する場合があります。
l 本文を含めて、本ブログの内容に関する責任および閲覧に伴う責任は負いかねます。
本文の方針
PDFファイルにした本文でも、基本となる事項を述べたうえで具体的な事例を取り上げています。
l 序盤では、それぞれのタイトルに関して基本となる事項を主に箇条書きで表しました。
l 中盤では、陥りやすい事例とその見直し例を対比して解説しました。
l 最後に「まとめ」として要約を述べるとともに、「後記」として目次に表した項目では述べきれない事項を補足しました。
冒頭で述べたとおり、わかりやすい技術文書を作成するには何よりも基本が大切です。見出しの付け方一つとっても、何が基本であるのかがほとんど知られていないように思えます。本ブログでは、技術文書を構成する要素それぞれの基本を明確にすることを第一にしました。
だからといって、基本を述べているだけでは実務につながりません。そこで、私がこれまで見てきた数多くの実例から共通して陥りやすい事項を整理して、基本に沿った直し方を加えました。「ブログ」と呼ぶには無理があるほど長大な内容になりましたが、実務に役立つ内容を目指した結果です。
例文の方針
本文であげた例文および図・表は、公知の事実をもとにした創作です。あくまで、技術文書の書き方を考えるうえでの事例であると理解してください。
l 例文の内容や例文中の名称などは、すべて架空のものです。また、実在の技術名などを使った例文も筆者の理解によるものであって、その内容に誤りが含まれている場合があります。
l 想定する文書の種別、読者対象によって用語の使い方を変えている箇所があります(例:パソコン/PC/クライアント)。
l 例文の趣旨を示すために下線などを補足しています。
l 例文の趣旨を優先する都合上、書式を簡略化している箇所があります。
コメントへの対応
質問・お問合せを含めていただきましたコメントには、特にお答えいたしません。本ブログへの評価および誤りのご指摘はありがたくお受けしますが、ご返事を差し上げない場合があります。また、コメントは随時に削除する場合があります。ブログを通じてのやりとりは望んでおりませんので、失礼になる場合もありますがご了承を願えますと幸いです。
「日本」の読み方を「にっぽん」とも「にほん」とも決められないのと同じく、言葉、文および文書の表し方はさまざまです。本ブログは、筆者である私が考える「技術文書の書き方」です。個人あるいは個々の企業の書き方を否定するものではありません。納得できる部分だけご自身の文書作成に取り入れていただければ十分です。
本ブログの取扱い
当ブログの利用は、著作者が公開するSNSでの閲覧に限ります。
技術文書の書き方
製作・著作 Takaaki Yamanouchi © 2024
l 一部あるいは全部にかかわらず当著作物を引用・転載・複製・保存する行為および他者に開示・貸与・配布する行為を禁じます。また、コンピュータなどを使用して内容を読み取る行為を禁じます。
l 当著作物から二次著作物を作成する行為を禁じます。ここでいう二次著作物の作成とは、当著作物を原案とした著作物を作成する行為、当著作物を翻訳する行為、インターネットや放送などによって公開する行為、講演や講習会などに使用する行為、AIなどに取り込んで利用する行為、その他を含みます。
不許複製 All rights reserved.
上記の事項は、各タイトルに添付されたPDFファイルにも及びます。
コメント
コメントを投稿