# Basics Of Technical Documentation For Engineers -解釈と分析-

[](https://hackmd.io/g05ngzQtQGmH-ERM2aq7Sw)


## 1. 元記事

[Basics Of Technical Documentation For Engineers](https://medium.com/datasheetest-by-tdsmaker/basics-of-technical-documentation-for-engineers-36deab8d1220), Ayca LITTLE, 25 April 2018, Published in
[DatasheetEST by TDSmaker](https://medium.com/datasheetest-by-tdsmaker)

## Introduction -導入-

### 原文と和訳

> In engineering, technical documentation refers to any type of documentation that describes the handling, functionality and architecture of a technical product or a product under development or use.
> In this article, I am going to mention how technical documentation produced in a dynamic and reactive organization will lead to increased sales and reduced marketing costs while greatly improving customer relations, satisfaction and retention.
> This might be a bold statement, but with the right processes, workflow management, team skills and tools to help you, this is a very real and achievable goal.

エンジニアリングにおいて、技術文書とはその種別に関係なく技術製品や開発中・利用中の製品の操作・機能・設計を説明する文書に言及するものである。
本記事において筆者は、動的で状況の変化に対して受動的な組織が生み出した技術文書が、顧客の関係性や満足度・囲い込みを向上される一方で結果的にどのように売上の増加やマーケティングコスト削減に結びつくかに言及する。
この技術文書と売上の増加やマーケティングコスト削減の相関関係は大胆な発言かもしれないが、正しい過程やワークフロー管理、チームスキルや有用なツールがあれば、これはかなり現実的で達成可能な目標である。

### 要点整理と考察

導入なので抽象的な内容しかなく、この時点では特になし。

## 1. Why we define data sheets as technical documents -我々がデータシートを技術文書と定義する理由-

### 原文と和訳

> Technical documentation comes in many different formats and is usually intended for a diverse range of recipients.
> **The common thread between all of these is that the documentation should convey in an efficient and appealing way the key information about the product or process they are promoting.**
> Some examples of these are [data sheets](https://blog.tdsmaker.com/why-data-sheet-are-one-of-the-most-important-bridge-for-sale), [product sheets](https://blog.tdsmaker.com/what-makes-good-product-spec-sheets/), user manuals, [product specification sheets](https://blog.tdsmaker.com/specification-sheet-vs-tech-pack-what-is-the-difference/), etc.
> As an example, data sheets give an overview as well as a detailed specification table for a featured product.
> This provides information that will be used by suppliers as well as by the end customer.
> So, we can see that data sheets can communicate with many different audiences whether it be the marketing department, fellow engineers or the customer.
>
> The common properties of a data sheet are that it defines what the product will do, how it will function, how and where it should be applied or used as well as other product specific information.
> Often you will find that the product documentation is drawn up directly by the manufacturer and should always accompany the product itself.
> Technical documents are written chiefly with the contribution of technical departments or technical writers.
> But non-technical documents are centered upon design issues and generating leads.
>
> “Brochures, leaflets or white papers are not classified as technical documents due to their marketing statements. “
>
> As we have already mentioned, data sheets can address many different types of audiences such as suppliers, manufacturers and customers.
> According to research done by IBM, **88% of customers make use of technical product information to make their purchasing decisions.
> The fact that these data sheets are seen as factual and scientific will often create a sense of trust in the contents by the consumer**.
>
> **At the simplest level, documentation is a form of communication.**
> **Effective technical communication conveys complex information to specific audiences clearly and accurately.**
> **It will allow your customers to use your products and services more effectively, as well as increasing customer satisfaction and loyalty.**
> The writing style and delivery method should be based on the audience and it is a key component in a complete product package.
> Increasingly, this is becoming a more and more important part of the sales presentation in today’s competitive markets.
> Well written documentation will play an important part in increasing your reputation with the documents intended audiences.
> Product documentation can be a great marketing asset for promoting both your product and your company.

技術的な文書は様々な書式で書かれることが多く、幅広い読者を想定している場合が多い。
**多様な書式を一本の糸で繋ぐ共通点は、文書化は効率的かつ魅力的な方法で、書き手が宣伝したいキーとなる情報を読者に伝えることである。**
それを行うための書式例にはデータシート、製品シート、ユーザーマニュアル、製品仕様書シートなどがある。
一例として、データシートは目玉商品の詳細な仕様だけでなく概観も示してくれるのだ。データシートが提供する情報は、末端顧客だけでなく製品やサービスの提供者にも利用される。
よって、読者がマーケティング部門や身内の技術者、顧客のうちの誰であろうとデータシートは多様な読み手とコミュニケーションを取ることが出来るのだと知ることが出来る。

データシートが共通して持つ特長は、その製品がどんな役割を果たすのか、どのように機能するのか、どのように/どんな状況で利活用されるかを明確に定義していることであり、その他特定の製品情報を提供するだけに留まらない。
製品文書は製造者によって直接作成され、それが常に製品に付属されるべきと感じることが多いだろう。
技術文書は主に技術部門または技術的執筆者が貢献し作成されている。
しかし、非技術文書においてはデザイン問題やリード創出(見込み客の獲得や潜在需要発掘のための営業活動)が中心的な関心事になる。

「パンフレットやチラシ、ホワイト・ペーパー(概要を理解した読者を対象に、さらに一歩掘り下げた内容を説明した文書)は、マーケティング視点の意見によって技術文書に分類されない。」

既に述べたように、データシートは供給者・製造者や顧客など多様な読み手に情報を提供する。
**IBM によって行われた研究によると、88% の顧客は技術的な製品情報を購入の意思決定に利用するそうだ。**
**データシートが事実に基づいた科学的な文書であるという事実によって、顧客はその内容に信頼を持つことが多い**。

**最も単純なレベルで言及すると、文書とはコミュニケーションの 1 つの形である。**
**印象的な技術文書は複雑な情報を、特定の読み手に明確かつ正確に伝えるものだ。**
**明確かつ正確な情報の伝達によって、顧客が自社の製品やサービスをより実用的に使うことができ、顧客の満足や愛着を強めるだけに留まらない。**
書式や公開方法は読み手によって変わって然るべきものであり、完成版製品パッケージの重要な要素である。
読み手によって手法を変えることが、今日の競争の激しい市場における販売プレゼンテーションにおいて益々重要な一翼を担う。
上手に書かれた文書は、その内容が想定読者層に適切に刺さっていることで自社の名声を高めるにおいて重要な役割を担う。
製品文書は製品と企業の両方を宣伝するための優れたマーケティング資産となり得る。

### 要点整理と考察

#### 原文(マーケティング)の観点

- 文書化とは、書き手が伝えたい重要な情報を効率的かつ魅力的な方法で読者に伝えることである
- 重要ではない情報はノイズである
- 読者に「伝わる」ためには、「効率的」で「魅力的」でなければならない
- 効率的: 最小の労力で必要な情報が過不足なく手に入ること
- 魅力的: ついつい読み入ってしまうような、または読後印象に強く残るような文体や表現方法
- 顧客の多くは、事実に基づいた科学的な製品情報があると製造企業や製品に信頼を持ちやすい
- 科学的: いつ、どこで、誰が読んでも同じ解釈になるという冪等性があることが安心感に繋がる
- 逆を言えば、^ がなければ 12% 未満の顧客しか囲うことが出来ない → もはやマーケティングに文書は不可欠である
- 文書とはコミュニケーションの 1 つの形である
- 「伝える」という意味では、基本的に読者からのレスポンスは期待値にないので、一方通行のコミュニケーションではある
- ただし、顧客フィードバックによって洗練される可能性はあるので、そういう意味では相互的なコミュニケーションである
- 複雑な情報を特定の読み手に明確かつ正確に伝える
- 読者層の想定: ペルソナ設定
- 明確かつ正確に: 読み手目線の語彙や表現で、過不足や誤謬がない状態
- このコミュニケーションの質が高いほど、顧客は自社製品・サービスの良質なユーザーとなり、同時に顧客の満足と愛着を育むことが出来る
- 文書はユーザーとの最重要インターフェースと言える

#### 社内ドキュメントの観点

- 文書とは、書き手が伝えたい重要な情報を効率的かつ魅力的な方法で読者に伝えることである
- 重要ではない情報はノイズである
- 読者に「伝わる」ためには、「効率的」で「魅力的」でなければならない
- 効率的: 最小の労力で必要な情報が過不足なく手に入ること
- 魅力的: ついつい読み入ってしまうような、または読後印象に強く残るような文体や表現方法
- 関係者の多くは、現状の仕様や運用に追従した最新の文書があるとチームやプロジェクトに信頼を持ちやすい
- 科学的 = いつ、どこで、誰が読んでも同じ解釈になり、同じ手順を踏めば同じ結果になるという冪等性があることが安心感に繋がる
- 逆を言えば、^ がなければ不信感を買い、意欲や生産性を損なう可能性が高い → もはやチームやプロジェクト運営に文書は不可欠である
- 文書とはコミュニケーションの 1 つの形である
- 社内ドキュメントの場合、誤謬や不明確な表現はメスが入ることが多く、基本的に双方向的なコミュニケーションである
- 複雑な情報を特定の読み手に明確かつ正確に伝える
- 読者層の想定: 開発者、TPM、デザイナー、プランナーなど、どの程度のステークホルダーが読むことを想定するか
- 明確かつ正確に: 技術者向けであれば抜け漏れのない網羅性の高さを、非技術者も読者に含むならば網羅性より分かりやすさを優先し簡潔さを求める
- このコミュニケーションの質が高いほど、関係者はチームやプロジェクトに積極的なコミットを行い、同時に意欲と生産性を高め得る
- 文書はチームやプロジェクトへの参画者との最重要インターフェースと言える

## 2. What are the benefits of data sheets? -データシートがもたらす恩恵とは何か？-

### 原文と和訳

> When we look at how marketing and technical documentation come together we can see that the content creators for both types of documentation are creating content for the same target audience, the customer.
As a result of this, we can see how important those content creators and the content they create is to [the success of the company](https://www.investopedia.com/articles/stocks/08/secrets-success-company-stock.asp) and the products that they are documenting or marketing.
**It is clear to see that the better different departments are able to communicate, share and work together, the better the final product, documentation and sales will be.**
>
> It is through the integrated use of easy to define and manage workflows and processes that technical documents can be created.
Ensuring that your engineers and marketers can collaborate through sharing templates, design systems and effective checks and balances will mean **your company can be trusted for consistent, accurate and relevant product information customers can rely on and use**.

マーケティング文書と技術文書がどのように調和するのかを考察すると、コンテンツ制作者はどちらも「顧客」という同じ対象に向けた中身を制作しているのだと分かる。
結果として、コンテンツ制作者や彼らが作り出すものは、企業と彼らが文書化もしくは売り込みを鋭意行っている製品が成功するためにいかに重要かが分かる。
**異なる部署同士が意思疎通を行い、分担し、協働することがより出来れば出来るほど、それに比例して最終的な製品や文書、売上げはより改善するだろう。**

技術文書が作成されるワークフローや過程を定義・管理することはマーケティング部門と技術部門が同じテンプレートを使うことによって容易になる。
自組織の技術者やマーケターがテンプレートの共有を通じて共同出来ることが保証されていれば、設計方針や効果的な部門間の力関係における抑制と均衡が存在することは、**一貫性があって精密で関連度の高い製品情報があり、そしてそれを顧客が信頼して利用することにより、自社が(顧客にとって)信頼出来る**ことを意味する。

### 要点整理と考察

#### 原文(マーケティング)の観点

- 違う部署同士が意思疎通と分業・協業が出来るほど業績に良い影響を与える
- 文書の質は製品の質を高め、良質な顧客を呼び込み、最終的に売上げの向上に繋がる
- 逆に言えば、組織が縦割りであるほど部署感のシナジー効果は望めず、売上にスケーリングにも限界が来る
- 顧客の自社の製品やサービスへの信頼の源泉となるのは「科学的」な製品情報である
- 一貫性がある = いつ、どこで、誰が見ても再現性がある状態
- 精度の高い = 事実と乖離のない情報が参照できる状態
- 関連度の高い = 必要な情報が抜け漏れのない状態

#### 社内ドキュメントの観点

- 同じチーム・プロジェクトのメンバー間だけでなく、時として違うチーム間での意思疎通と分業・協業が出来るほど社内文書の質は高まる
- 参画者の生産性と意欲の向上に寄与する
- 意思疎通と分業・協業がないほど、生産性や意欲は下降の一途を辿る(経験済み)
- 社内文書のためにどれだけステークホルダーの工数を確保できるかはボトルネックの 1 つである
- 参画者のチーム・プロジェクトへの信頼の源泉となるのは「科学的」な文書である
- 一貫性がある = いつ、どこで、誰が見ても再現性がある状態
- 精度の高い = 事実と乖離のない情報が参照できる状態
- 関連度の高い = 必要な情報が抜け漏れのない状態

## 3. Why Technical Content and Marketing Belong Together -技術的内容とマーケティングが共存する理由-

### 原文と和訳

> There is also a key area of documentation that is often overlooked or ignored completely by companies: post sales documentation.
This follow-up documentation will often help a customer to understand and better use your products after the point of sale.
> **Rather than abandoning your customer once the purchase has been made, by providing these additional services or documents you will have created an additional opportunity to market and sell additional products to an already converted (hopefully loyal) customer.**
> A fantastic example of this are websites and online resources which customers can go to and through which you can target and advertise new or associated products to the customer directly.
> **It is essential that this service is provided in a clear and precise manner that brings benefits to the customer so that you will, in turn, benefit from the increased brand loyalty that will be engendered in your customer.**
>
> **It’s apparent that the marketing and engineering professionals in charge of creating these technical documents about complex processes need to be able to communicate the information in a manner that is both appealing and easy to understand from a customer’s point of view.**
> This means that they must take on the additional roles of user advocates, researchers, testers and publishers.

企業によって完全に無意識に見過ごされている、もしくは意図的に無視されている重要な文書分野もまた存在する。
それこそが販売後の文書だ。
このフォローアップ文書は、製品の販売後に顧客が自社のそれを理解してより良い使い方をするのに役立つ。
**(まるで釣った魚に餌をやらないように)購入が完了したら顧客を無碍にするよりも、むしろ先述のフォローアップ文書のような付加サービスや文書を提供すると、さらなる製品をすでに自社の(願わくば)お得意様となった顧客に対して売り込んで販売する機会の創出を達成することだろう。**
この面白い例がウェブサイトや、顧客が直接アクセス出来たり企業がそれを利用することで直接顧客に新製品や関連製品を対象化して広告することが出来るオンライン上のリソースだ。
**顧客に対して分かりやすくて求められた恩恵をもたらすやり方でサービスを提供することは必要不可欠であり、その結果今度は自分が顧客の中に醸成されるブランドへの愛着から恩恵を受けるだろう。**

**複雑な過程に関する技術文書を作成することを担うマーケティング・エンジニアリングの専門家が顧客視点に立ち、思わず読みたくなるだけでなく理解しやすい方法で情報を伝えることが出来る必要があることは明らかである。**
つまり、彼ら専門家がユーザーの代弁者や研究者、テスター、出版者という更なる役割を請け持たなければならないのである。

### 要点整理と考察

#### 原文(マーケティング)の観点

- 獲得した顧客には継続的に手厚いサービスを提供し続ける必要がある
- 暫定対応ではなく恒久対応
- 顧客目線で分かりやすい情報やサービスを提供することが、顧客の自社製品への愛顧を勝ち取るためには必要不可欠であり、同時に勝ち取った顧客の愛顧は自社の製品の更なる購入を促す
- ^ は相互作用的である
- 技術的難易度の高い文書を書く者の責務は、それを集約・体系化することだけでなく、少なくとも想定読者層の視点に立ち魅力的かつ理解しやすく情報を伝えることにも及ぶ
- 大いなる知見には大いなる説明責任が伴う

#### 社内ドキュメントの観点

- ドキュメントを作成したからといって参画者に「これ読んでおいて」のように丸投げするのではなく、あくまでそれを叩き台に継続的にオンボーディングをサポートする必要がある
- 放置プレーはチームやプロジェクトへの帰属意識を著しく低下させる
- 理解しやすい継続的な情報提供はスムーズなオンボーディングを実現し、参画者は高いモチベーションと生産性をチームやプロジェクトに還元してくれる
- イニシャルコストは投資で、適切に掛ければ長い目で見れば享受できるだけの恩恵がある
- 技術的難易度の高い文書を書く者の責務は、それを集約・体系化することだけでなく、少なくとも想定読者層の視点に立ち魅力的かつ理解しやすく情報を伝えることにも及ぶ
- 大いなる知見には大いなる説明責任が伴う
- 説明責任が大きくなる前に知見が属人化しないように先手を打っておく必要はありそう(一気阿生にはなかなかできない)

## 4. Why Technical Content and Marketing Belong Together -技術的内容とマーケティングが共存する理由-

### 原文と和訳

> Emotions are natural human drives that dictate how we behave and what we do.
> **They are the main influencers in our decision-making processes.**
> **They can create and maintain strong emotional ties with certain brands, and when brands evoke emotions in their consumers, those emotions then influence further brand related decision-making such as buying additional products from the same brand over a market competitor.**
> They influence how we shop and what we buy and they are more effective than logic in advertising.
> Emotion plays a surprisingly large role in B2B market, Black Friday is a perfect example of this dynamic in play and as a result, the best marketing campaigns connect a truly awesome product with a creative, emotional advertisement to create a sense of connection with the customer.
>
> One of the largest (and most profitable) examples of this currently is the annual ‘Singles Day’ sales in China which leads to around 700 million transactions and product purchases in a day, which is many billions of dollars of revenue and sales.

喜怒哀楽の感情は私たちの振舞いや行動に影響を与える人間に生来備わった原動力である。
**それらの感情は私たちの意思決定の過程に大きな影響を及ぼす。**
**それは特定のブランドとの強い感情的な繋がりを作り出して維持し、そのブランドが顧客の感情に訴えるものがあると、それらの感情はそれから他の競合ブランドより(以前購入したのと)同じブランドの追加製品を購入するようなブランド起因の意思決定をさらに左右する。**
喜怒哀楽の感情は私たちの買い物の仕方や購入品を左右し、広告においては理論で訴えるより購入を促進するものだ。
感情は対企業の市場に驚くほど大きな役割を果たす。
ブラックフライデーはこのケースで働く心理的原動力の完璧な例の 1 つである。
結果として最良の販売運動は実際に優れた製品と創作的・感情的な広告を関連付け、顧客との繋がりという感覚を作り出すのである。

対企業の市場において働く心理的原動力の最も大きな(そして有益な)例は、現在においては中国で毎年開催されて 1 日で 7 億の取引と製品購入が行われる「独身の日」セールであり、その収益と売上は数百万ドルに上る。

### 要点整理と考察

#### 原文(マーケティング)の観点

- 人間に生来備わった原動力である喜怒哀楽の感情は意思決定の過程に大きな影響を及ぼす
- 人間は最終的な意思決定を理論より感情で行う傾向がある
- マーケティング分野においては、製品品質が一定以上であることが前提ではありつつも、それだけが同じブランドやサービスを愛顧し続ける理由ではない
- → どんな広告がユーザーに刺さるのか、きちんと狙って打たなければ売上・収益に繋がらない

#### 社内ドキュメントの観点

- 人間に生来備わった原動力である喜怒哀楽の感情は意思決定の過程に大きな影響を及ぼす
- 人間は最終的な意思決定を理論より感情で行う傾向がある
- 社内ドキュメントにおいては、チームやプロジェクトの運用方法の妥当性やドキュメントの品質が一定以上であることが前提ではありつつも、それだけがモチベーションや生産性を維持する原動力とはならない
- → 参画者の感情にも目を向けてケアをする必要がある
- ^ はドキュメントでどうやって実現出来る？

## 5. How Engineers and marketing can come together and bring more success to your business -どのように技術者とマーケティングが一体となってビジネスにより大きな成功をもたらすか-

### 原文と和訳

> Engineers have their own visual language which they use to communicate information about their products.
> Visual aids such as charts, graphs, tables, diagrams, mathematical symbols, detailed product blueprints and engineering drawings are all used to describe the product or application on offer.
> It may seem like a cliché, but in many companies around the world, **Marketing and Engineering departments often don’t come into contact with each other and when they do they don’t always see eye to eye**.
>
> **It is important for companies to come up with a system and workflow processes that allow for efficient communication and information sharing between these two departments so that products can be properly described and marketed.**
> **Effective use of technical documentation can lead to greater customer engagement and, therefore, more successful product sales and customer experiences.**

技術者には自らが開発に携わっている製品についての情報を伝えるために利用する視覚的な伝達手段がある。
図表・グラフ・表・略図・数学記号・詳細な製品の青写真や機械製図などの視覚材料は全て販売中の製品かアプリケーションを説明するために使われる。
ありふれたことのように思えるかもだろうが、世界中の多くの企業において、**マーケティング部門とエンジニアリング部門はお互いに接触することは多くなく、例え接触したとしてもいつも見解が一致する訳ではない**。

**製品が適切に説明され売り出されるためには、企業がこれら 2 部門間の効率的なコミュニケーションや情報共有を斟酌したシステムや作業過程を用意することが重要である。**
**効果的に技術文書を活用することが、顧客エンゲージメントをより高め、結果として製品の売行きや顧客体験をより大きな成功に導く。**

### 要点整理と考察

#### 原文(マーケティング)の観点

- 製品やサービスがセールスや顧客体験の観点で成功するためには、技術者部門が持つ視覚的な説明材料とマーケティング部門がその共有を受けた上でそれらを売り出すためのコミュニケーションの礎が企業内に必要である

#### 社内ドキュメントの観点

- チームやプロジェクトが顧客体験や作業者体験の観点で成功するためには、技術者部門が持つ視覚的な説明材料と非技術者がその共有を受けた上で作業や開発を進めていくためのコミュニケーションの礎が企業内に必要である
- 現実的には視覚的な説明材料を持っている開発チームは多くなくて、むしろソースコードから仕様を非技術者が分かる言葉に変換する技術が重要である
- ただし、冪等性のある作業を毎回行うのは無駄の極みなので、集約・体系化した上で明文化する動きを日頃から取ることが肝要である

## 6. Must-Have Skills for Engineers to have success ın technical documentation and product marketing -技術者が技術文書と製品マーケティングで成功するための必須スキル-

### 原文と和訳

> **Clear Communication Skills**
> It is vital to be able to communicate in a clear manner so that you can effectively explain instructions and processes as well as present problems and solutions to both clients and the team members.
> Without clear communication, the possibility of a project failure is very high and within the engineering fields, it is crucial to success.
>
> **Collaboration**
> Whether you call it cooperation, collaboration, or teamwork, an engineer’s ability to work with other people from different backgrounds is essential.
>
> **Dealing with pressure**
> Managers should be able to lead a team in a way that fosters cohesion, communication and collaboration so that if and when a problem arises, everybody is on hand to tackle it.
> If issues aren’t resolved in a short space of time, they could potentially prove costly for the organization and reflect badly on the team.
>
> **Problem-solving skills**
> Engineers are often called upon to address problems on their own and must be able to figure out where the problems come from and provide solutions.
>
> **Team players**
> Becoming the head of a project, one must be able to encourage, empower, and help to improve team members.
> We must be able to work with others to in order to achieve our goals.
>
> **Thinking Ahead**
> It is important for engineers to be able to anticipate problems in the product’s development process.
> The ability to foresee issues in the project and identify possible sticking points means they can be addressed and resolved before causing any real delays or increased costs within the project.

**分かりやすく伝えられること**
取引先とチームメンバーの双方に、目下直面している問題とその解決法だけでなく手順や過程を効果的に伝えることが出来るためには、分かりやすい方法で物事を伝える能力は極めて重要である。

**他者と協業出来ること**
それを協力、協業、またチームワークと呼ぼうとも、異なる経歴・背景を持つ他者と協業する能力は技術者にとって不可欠である。

**困難と上手く付き合えること**
管理者は団結や意思疎通、協業する土壌を育むようにチームを牽引することが出来るべきであり、その結果問題が発生した時にはそれに立ち向かうために(チームメンバーの)皆が稼働出来る状態になる。
もし短期間で解決しない場合は、その問題がチームの手に余るものである可能性があり、そのチームの評判を落とし得る。

**問題解決能力を有していること**
技術者は自力で問題を解決することが求められることが多く、その問題がどこから発生しているのかを理解して解決策を提示することが出来なければならない。

**チームとして動けること**
プロジェクトの長となると、チームメンバーを強化することを促し、力づけ、助けることが出来なければならない。
私たちは共通の目標を達成するために他者と協業出来なければならないのだ。

**先んじて物事を考えられること**
技術者にとって、製品開発の過程において発生する問題を予見出来ることは重要である。
そのプロジェクトにおける問題を予見して障害となっているものを特定出来ることは、プロジェクト内でいかなる遅延やコスト増大が発生する前にその問題を解決出来るのと同義である。

### 要点整理と考察

原文ママなのでなし

## 7. What strategies can you use to improve your technic documents and marketing approach? -技術文書とマーケティング方策を改善するためにはどんな戦略が利用出来るか？-

### 原文と和訳

> **It can often be a challenge to keep your documentation up-to-date, accessible, and looking professional.**
> There are many different people involved in creating and maintaining the data sheets often with complex and distributed workflow structures.
>
> This means **there can be a large overhead in managing these different teams and communicating changes and product updates in an effective and timely manner**.
> More and more companies are choosing to host their technical documentation on their corporate website so that these can be easily kept up to date as well as being a dedicated resource from which suppliers, manufacturers, regulators and customers can come back to again and again.
> **It is worth investing the time and effort into creating great documentation as this is an investment into the product and into the future of the company.**
>
> **Your brand and your products need to be consistent in message, form and presentation — having effective documentation will reiterate your message and ensure consistency.**
> **Your documentation should be written from the perspective of the users and take into consideration what they already know as well as what they are trying to do and how they are trying to do it.**
> You should consider how they will access the product, the documentation, how they’ll communicate to friends and family or co-workers, and about a hundred other important aspects.
>
> This means that having well-defined, collaborative workflows and processes will ensure that none of these are missed, but also that the relevant people are not being flooded with irrelevant information or requests.
>
> **Each time users find the answers to their queries in the documentation, the company saves time and money.**
> **So, taking time to provide answers to the most common questions within your technical data sheets is a worthwhile investment.**
> **Documents should be designed, prepared, reviewed, and distributed within the boundaries of properly managed workflows and by the appropriately trained and authorized team members.**
> **Therefore having a system that allows for dynamic and easy to structure team permissions within workflows will lead to more efficient creation of and maintenance of the technical data sheets.**

**文書を最新状態に保ち、参照出来てなおかつ専門的に見え続ける状態を保つのは困難であることが多い。**
複雑でばらばらのワークフロー構造を持つデータシートの作成と運用には多くの異なる部門の人々が関わっている。

この事実は、**これら関係者の様々な部門を管理したり、製品の変更や更新情報を効果的でタイムリーな方法で伝えることにおいては、本質ではない大きな付帯的コストが存在し得る**ことを意味する。
益々多くの企業が自前のウェブサイトに技術文書を掲載することを選択し、その結果技術文書は容易に最新化することが出来、製品やサービスの提供者や製造者、監査機関、顧客が何度も何度も訪れることに特化した資源であるだけに意義は留まらない。
**技術文書は製品とそれを扱う企業の未来への投資であるため、優れた文書に時間と労力を投資する価値はある。**

**自社のブランドや製品は、それが伝えんとすることや形式、体裁が一貫している必要がある。**
**つまり、効果的な文書は文言を冪等性を持って読み手に繰り返し伝え、一貫性を担保する。**
**技術文書はユーザー視点で書かれるべきであり、そしてそれはユーザーが試みている内容やその方法だけでなく彼らが既に知っていることも斟酌すべきなのである。**
ユーザーが製品や技術文書をどのように知るか、ユーザーが友人・家族・同僚にどのようにそれらを伝えるか、そしてその他数多の重要な側面を考慮すべきである。

つまり、定義が明らかで協業的なワークフローや過程はこれらのいずれも見落とすことがないだけでなく、無関係な情報や要求の波に関係者が飲み込まれることもない。

**ユーザーが文書内で問合せ内容に対する回答を見つける度、企業は時間とお金を節約することになる。**
**だからこそ、技術データシート内で最も頻繁に受ける質問に対する回答を提供するために時間を使うことは価値のある投資なのだ。**
**文章は設計され、準備され、レビューを受け、適切に管理されたワークフローの境界内で、適切に訓練を受けた権限を持ったチームメンバーによって配布されるべきである。**
**ゆえに、ワークフロー内でチームの権限を構築することを動的かつ容易にする仕組みによって、技術データシートの作成・運用はより効率的になる。**

### 要点整理と考察

#### 原文(マーケティング)の観点

- 社内の関係者が多く関わる技術文書ほど最新の情報に追従させるのに困難が伴う
- 製品の変更や更新が多くの人を介した伝言ゲーム伝わるため、正確性とリアルタイム性の担保が難しい
- 技術文書は製品とそれを扱う企業の未来への投資である
- 一度文書を完成させ導線を整備さえすれば、ユーザーから頻繁に受ける同じ問いには人の手を介さず冪等性を持って同じ答えを返すことが出来る
- ^ 問合せごとに割く人員もお金も不要になるため、属人性の排除とコスト削減が期待出来る
- だからこそ、長い目で見ると投資した初期コスト以上のメリットがあり、それが製品とそれを扱う企業の未来に寄与する
- 特に企業サイトに技術文書を掲載する企業が増えている
- 企業サイトユーザーや取引先、顧客にとってのインターフェースであり、かつ何度も訪問されるため、社会的信用を得るために重要な役割を果たす
- 技術文書の品質が一種の企業ブランディングになっている
- 文書の品質が信用に値するものであれば、製品や企業に対する信用に繋がる
- 技術文書はユーザー視点で書かれるべきである
- 顕在的・潜在的ニーズの双方の内容が盛り込まれているのが理想的な文書の形である
- 技術文書は適切なワークフローの中で、設計・執筆・レビューを受け、然るべき範囲に権限を持ったメンバーによって公開されなければならない
- 設計: 読み手が情報を探しやすい構成にする
- 執筆: ユーザー目線の分かりやすい表現で、情報に過不足なく、機密情報を含まず、適切な情報を適切な表現で説明する
- レビュー: ユーザー目線の分かりやすい表現になっているか、情報に過不足はないか、機密情報を含んでいないかをチェックする
- 範囲: 参照して良いステークホルダーにだけ情報を共有する
- 権限: 設計～公開の全てのフェーズに対する責任を負うことが出来る然るべきメンバーを任用する

#### 社内ドキュメントの観点

- 社内の関係者が多く関わる技術文書ほど最新の情報に追従させるのに困難が伴う
- 製品の変更や更新が多くの人を介した伝言ゲーム伝わるため、正確性とリアルタイム性の担保が難しい
- 社内ドキュメントの場合にはドメイン(知見の領域)やステークホルダ(関係する職種)を絞ることでコントロール可能
- 技術文書はチームやプロジェクト、自社の未来への投資である
- 一度文書を完成させ導線を整備さえすれば、ステークホルダーから頻繁に受ける同じ問いには人の手を介さず冪等性を持って同じ答えを返すことが出来る
- ^ 問合せごとに割く人員もお金も不要になるため、属人性の排除とコスト削減が期待出来る
- だからこそ、長い目で見ると投資した初期コスト以上のメリットがあり、それが製品とそれを扱う企業の未来に寄与する
- オンボーディング資料や社内 Handbook に技術文書を掲載するのは有益な方法である
- ステークホルダー(既存、新規参画者含む)にとってのインターフェースであり、かつ何度も参照されるため、チームやプロジェクトに対しての信頼度の観点で重要な役割を果たす
- 技術文書の品質がそのチームやプロジェクトにとっての一種のブランディングになっている
- 文書の品質が信用に値するものであれば、そのチームやプロジェクトに対する信用に繋がる
- 技術文書はユーザー視点で書かれるべきである
- 想定読者層をどこに設定するかが重要
- 技術者であれば、その文書を読むにあたりどの程度の技術的知見を有していることを前提とするか
- 非技術者も対象とするのであれば、どの程度詳細に説明するか
- 詳細すぎると却って混乱を生む
- 抽象度の高い概念は視覚材料(図表など)を盛り込むと理解の助けになる
- 顕在的・潜在的ニーズの双方の内容が盛り込まれているのが理想的な文書の形である
- 不確実性の予見には限界があるので、社内ドキュメントの場合はここに力を入れすぎないこと
- 全員が理解出来る技術文書を作ることは不可能だと考えたほうが良い(全人類が「美味しい」と唸る料理を発明するくらい難しい)
- 技術文書は適切なワークフローの中で、設計・執筆・レビューを受け、然るべき範囲に権限を持ったメンバーによって公開されなければならない
- 設計: 読み手が情報を探しやすい構成にする
- 執筆: ユーザー目線の分かりやすい表現で、情報に過不足なく、機密情報を含まず、適切な情報を適切な表現で説明する
- レビュー: ユーザー目線の分かりやすい表現になっているか、情報に過不足はないか、機密情報を含んでいないかをチェックする
- 範囲: 参照して良いステークホルダーにだけ情報を共有する
- 権限: 設計～公開の全てのフェーズに対する責任を負うことが出来る然るべきメンバーを任用する
- ただし、技術文書作成・運用においては権限を偏らせない方が効率的である

## 8. What are some of the common pitfalls in technical writing and product marketing? -技術文書の作成や製品マーケティングにおいてよくあるいくつかの落とし穴はどんなものか？-

### 原文と和訳

> When creating and maintaining technical documents, there are a number of issues and problems that can arise from producing a low standard of documentation such as:
>
> - Re-work
> - Re-design
> - Troubleshooting
> - Re-testing
> - Re-inspection
> - Delays
> - Equipment Downtime
> - Product recalls
>
> When it comes to poor management and workflow processes then issues such as these can occur:
>
> - Unexpected Overtime
> - Customer Complaints
> - Damaged Reputation
> - Loss of customer goodwill
> - Extra Setups and Disrupted Production Schedules

技術文書を作成・運用する際、低品質の成果物から生じる多くの問題が存在する。
以下に例を列挙する。

- 執筆やり直し
- 設計やり直し
- トラブルシューティング
- 再テスト
- 再検査
- 遅延
- 設備のダウンタイム
- 不良品回収

貧弱なワークフロー過程管理では以下のような問題が発生し得る。

- 予定以上の作業時間
- 顧客クレーム
- 評判の悪化
- 顧客信用の喪失
- 余計な段取りと製品スケジュールの中断

### 要点整理と考察

- 技術文書は一度着手したら、一定以上の品質を担保した成果物を出す義務が生じ、品質が担保されない成果物は百害あって一利なし
- 発生する問題は本文に書かれたものに加え、最悪の場合作った文書を廃棄せざるを得なくなり、せっかく費やしたコストが水泡に帰する場合もある
- 技術文書自体は直接利益を生むものではないため、シビアな費用対効果意識が必要だが、ケチりすぎると本文のような結末になるので、ある程度のコストは作業者・上長ともに覚悟するべき

## CLOSING -終わりに-

### 原文と和訳

> With all that being said, are there any products that will allow you to achieve a level of technical documentation for your products?
> Something that will lead to the types of benefits we have described?
> A product that provides:
>
> - Increased product sales
> - Increased customer satisfaction
> - Streamlined, dynamic and efficient workflow management
> - Integrated and easy to manage deployment channels for your technical data sheets such as HTML and PDF to suppliers, customers and your corporate websites
> - Integrated workflow user management tools to create dedicated and trackable processes for creating and updating your technical documentation
> - Real-time monitoring of customer interactions with your technical documentation such as download counts, etc.
> - New audiences to share and promote your technical data sheets via a web-based store.

そういう訳で、この記事を読んでくれたあなたが携わる製品の技術文書の水準を満たす製品は存在するだろうか？
説明してきたタイプの恩恵に繋がる何か収穫はあっただろうか？
(本当の意味での)製品というのは以下の恩恵をもたらしてくれる。

- 製品売上げの増加
- 顧客満足の向上
- 合理的で、動的で、効率的なワークフロー管理
- 製品やサービスの提供者や顧客、企業ウェブサイト向けの、HTML や PDF などのフォーマットの技術データシートの配信経路の統合的で容易な管理
- 技術文書の作成・更新に特化し追跡可能な過程を作るための、統合的なワークフロー・ユーザー管理ツール
- ダウンロード数など、顧客からの技術文書への接触のリアルタイムの監視
- ウェブストアを介した技術データシートを共有・宣伝する新しい読み手

### 要点整理と考察

原文ママなのでなし

## 社内ドキュメントの観点での要点整理と考察

## ドキュメンテーションとは？

- 情報を文書という媒体を通じて読み手に伝えるというコミュニケーションの 1 つの形である
- 文書はチームやプロジェクトへの参画者との最重要インターフェースと言える
- このコミュニケーションの質が高いほど、関係者はチームやプロジェクトに積極的なコミットを行い、同時に意欲と生産性を高め得る

### 社内ドキュメンテーションに必須の 6 大要素

1. 科学的であること
- 一貫性: いつ、どこで、誰が見ても再現性がある
- 精度: 事実と乖離のない情報が参照できる
- 関連性: 必要な情報が抜け漏れがない
2. 効率的であること
- 最小の労力で必要な情報が過不足なく手に入ること
3. 印象的であること
- 魅力的: ついつい読み入ってしまうような、または読後印象に強く残るような文体や表現方法
- 人間に生来備わった原動力である喜怒哀楽の感情は意思決定の過程に大きな影響を及ぼす
- 人間は最終的な意思決定を理論より感情で行う傾向がある
- 社内ドキュメントにおいては、チームやプロジェクトの運用方法の妥当性やドキュメントの品質が一定以上であることが前提ではありつつも、それだけがモチベーションや生産性を維持する原動力とはならない
4. 想定読者層が明確であること
- 技術者であれば、詳細度と網羅性の高さを優先する
- どの程度の技術・ドメイン知識を必要とするかの前提は必要
- 非技術者も対象とするのであれば、簡潔さ・分かりやすさを優先する
- 詳細すぎると却って混乱を生む
- 抽象度の高い概念は視覚材料(図表など)を盛り込むと理解の助けになる
5. 技術者と非技術者間のコミュニケーションの礎が企業内に確立されていること
- 現実的には視覚的な説明材料を持っている開発チームは多くなくて、むしろソースコードから仕様を非技術者が分かる言葉に変換する技術が重要である
- ただし、冪等性のある作業を毎回行うのは無駄の極みなので、集約・体系化した上で明文化する動きを日頃から取ることが肝要である
6. 技術文書は適切なワークフローの中で、設計・執筆・レビューを受け、然るべき範囲に権限を持ったメンバーによって公開されること
- 設計: 読み手が情報を探しやすい構成にする
- 執筆: ユーザー目線の分かりやすい表現で、情報に過不足なく、機密情報を含まず、適切な情報を適切な表現で説明する
- レビュー: ユーザー目線の分かりやすい表現になっているか、情報に過不足はないか、機密情報を含んでいないかをチェックする
- 範囲: 参照して良いステークホルダーにだけ情報を共有する
- 権限: 設計～公開の全てのフェーズに対する責任を負うことが出来る然るべきメンバーを任用する
- ただし、技術文書作成・運用においては権限を偏らせない方が効率的である

### 社内ドキュメンテーションに必須の 5 大スキル

1. 読み手目線の説明能力
- 目下直面している問題とその解決法、手順や過程を効果的に伝えることが出来るためには、読者視点で書かれるべきである
- 一貫性: いつ、どこで、誰が見ても再現性がある
- 精度: 事実と乖離のない情報が参照できる
- 関連性: 必要な情報が抜け漏れがない
2. ステークホルダーとの協業能力
- それを協力、協業、またチームワークと呼ぼうとも、異なる経歴・背景を持つ他者と協業する能力は技術者にとって不可欠である。
- 同じチーム・プロジェクトのメンバー間だけでなく、時として違うチーム間での意思疎通と分業・協業が出来るほど社内文書の質は高まる
- 参画者の生産性と意欲の向上に寄与する
- 意思疎通と分業・協業がないほど、生産性や意欲は下降の一途を辿る(経験済み)
- 社内文書のためにどれだけステークホルダーの工数を確保できるかはボトルネックの 1 つである
3. 問題解決能力
- 技術者は自力で問題を解決することが求められることが多く、その問題がどこから発生しているのかを理解して解決策を提示することが出来なければならない。
4. コスト管理能力
- もし短期間で解決しない場合は、その問題がチームの手に余るものである可能性があり、そのチームの評判を落とし得る。
5. 潜在的な問題の予測能力
- 技術者にとって、製品開発の過程において発生する問題を予見出来ることは重要である。
- そのプロジェクトにおける問題を予見して障害となっているものを特定出来ることは、プロジェクト内でいかなる遅延やコスト増大が発生する前にその問題を解決出来るのと同義である。

### 体系的社内ドキュメントの 3 大恩恵

1. 組織への信頼感の醸成
- 関係者の多くは、現状の仕様や運用に追従した最新の文書があるとチームやプロジェクトに信頼を持ちやすい
- 科学的 = いつ、どこで、誰が読んでも同じ解釈になり、同じ手順を踏めば同じ結果になるという冪等性があることが安心感に繋がる
- 逆を言えば、^ がなければ不信感を買い、意欲や生産性を損なう可能性が高い → もはやチームやプロジェクト運営に文書は不可欠である
2. 組織の参画者の意欲と生産性の維持・向上
- 理解しやすい継続的な情報提供はスムーズなオンボーディングを実現し、参画者は高いモチベーションと生産性をチームやプロジェクトに還元してくれる
- イニシャルコストは投資で、適切に掛ければ長い目で見れば享受できるだけの恩恵がある
3. 中長期的なコスト削減
- 技術文書はチームやプロジェクト、自社の未来への投資である
- 一度文書を完成させ導線を整備さえすれば、ステークホルダーから頻繁に受ける同じ問いには人の手を介さず冪等性を持って同じ答えを返すことが出来る
- ^ 問合せごとに割く人員もお金も不要になるため、属人性の排除とコスト削減が期待出来る
- だからこそ、長い目で見ると投資した初期コスト以上のメリットがあり、それが製品とそれを扱う企業の未来に寄与する

### 理想と現実の乖離 -不可避なトレードオフ-

- 社内の関係者が多く関わる技術文書ほど最新の情報に追従させるのに困難が伴う
- 製品の変更や更新が多くの人を介した伝言ゲーム伝わるため、正確性とリアルタイム性の担保が難しい
- 社内ドキュメントの場合にはドメイン(知見の領域)やステークホルダ(関係する職種)を絞ることでコントロール可能
- 技術文書は一度着手したら、一定以上の品質を担保した成果物を出す義務が生じ、品質が担保されない成果物は百害あって一利なし
- 発生する問題は本文に書かれたものに加え、最悪の場合作った文書を廃棄せざるを得なくなり、せっかく費やしたコストが水泡に帰する場合もある
- 執筆やり直し
- 設計やり直し
- トラブルシューティング
- 再テスト
- 再検査
- 遅延
- 設備のダウンタイム
- 不良品回収
- 貧弱なワークフロー過程管理では以下のような問題が発生し得る。
- 予定以上の作業時間
- 顧客クレーム
- 評判の悪化
- 顧客信用の喪失
- 余計な段取りと製品スケジュールの中断
- 技術文書自体は直接利益を生むものではないため、シビアな費用対効果意識が必要だが、ケチりすぎると本文のような結末になるので、ある程度のコストは作業者・上長ともに覚悟するべき