開発者向けテクニカルライティング

HTML、CSS、JavaScript、Python、PHP、C ++、Dart —そこには非常に多くのプログラミング言語があり、それらのいくつかに完全に堪能でさえあるかもしれません！ しかし、私たちがより多くのより良いコードを書くことを目指すにつれて、私たちが日常の言語で書き、コミュニケーションする方法はますます重要になります…そしておそらく見過ごされさえします。

コードについての記述方法は、コード自体と同じくらい重要です。 そして、あなたがその線に当たる場所にもかかわらず、私たちの言葉がコードの有効性を助け、傷つける可能性があることに私たちは皆同意することができます。

この記事では、プログラミングとライティングというXNUMXつの一見異なる分野を組み合わせて、開発者のスキルを次のレベルに引き上げる方法について概説します。

待って、テクニカルライティング？ はい、それはまさに私が言っていることです。 私たちは、ある意味で私たち全員が作家であると心から信じています。 そして、私はあなたに、それがあなたをより良い開発者とコミュニケーターの両方にする方法についてのヒント、アドバイス、そして例を書くための入門書をあなたに与えるためにここにいます。

テクニカルライティングはいたるところにあります

昨年、人気のあるMacGitクライアントであるTowerの背後にいるチームは 4,000人以上の開発者をポーリング そして、それらのほぼ50％が3日6〜XNUMX時間コードを書くのに費やしたことがわかりました。

はい、それはかなりニッチなグループを調査する24つの調査ですが、私たちの多くはその範囲のどこかに該当すると思います。 いずれにせよ、この世論調査が示唆するように、私たちは他のことをするのに多くの時間を費やしているので、開発者は7時間年中無休でコードを書いていません。

これには次のものが含まれる可能性があります。

• 新機能のデモ、
• その新機能を文書化して、
• その新機能に関連する作業チケットを更新する、または
• その新機能をサポートするためのバックログ作業。

もちろん、バスルームの休憩やWordleの時間も常にあります。

とにかく、私たちが通常行うことのほとんどは、チーム、同僚、クライアント、ユーザー、その他の開発者などの人々とのコミュニケーションに関係しています。

ですから、私たちは時間のかなりの部分を人間とのコミュニケーションに費やしています。 言葉 コンピュータとの通信に加えて コード。 言葉は書かれた言語です。 そして、私たちが自分の言葉をよりよく書くならば、私たちはより良いコミュニケーションをするでしょう。 私たちがより良いコミュニケーションをとるとき、私たちは私たちが望むものを手に入れる可能性が高くなります。

それがテクニカルライティング101です。

そして、それはここで終わりではありません。一部のプログラマーは、独自の製品を作ることも好みます。つまり、マーケティングを仕事の一部にする必要があります。 その中でもテクニカルライティングは大きな役割を果たします。 だから、ええ。 テクニカルライティングは 確かに どこにでも。

良い文法とは何ですか？

非常に多くのプログラミング言語があるので、私たちが最後に望んでいるのは、別の言語を学ぶことです。

文法 は英語の不可欠な部分であり、コミュニケーションの可能性を最大限に引き出します。 それは私たちをよりフォーマルで、プロフェッショナルで、首尾一貫したものにします。

言語について簡単に説明します。

英語の構文

プログラミング言語と同じように、英語には明確に定義された構文があり、単語で始まります。

単語は英語の構成要素であり、XNUMXつのバケットに分類されます。

これらを次のように考えてください UI コンポーネント：これらはモジュール式のピースであり、完全で堅牢な文を作成するために移動できます。これは、完全で堅牢な文をつなぎ合わせるのと同じ方法です。 UI。 すべてのコンポーネントが常に存在する必要がありますか？ 確かに違います！ インターフェイスの場合と同じように、エクスペリエンスを完了するために必要な部分を使用して文を組み立てます。

声とトーン

語彙、句読点、文型、および単語の選択。 これらはすべて英語の要素です。 私たちはそれらを使用して、アイデアを共有したり、友人や家族とコミュニケーションしたり、同僚にメールを送信したりします。

しかし、それを考慮することが重要です 音 私たちのメッセージの。 XNUMXつの感嘆符がメッセージのトーンを完全に変えることができるのは驚くべきことです。

1. 私はプログラミングが好きです。
2. I ような プログラミング！ :)

声とトーンを混同しやすく、その逆も同様です。

ボイス 文脈に依存する単語の選択に関係するものです。 たとえば、初心者向けのチュートリアルでは、俗語や非公式な言葉を使って親しみやすい声を伝える傾向がありますが、ドキュメントは、要点を明確にするために、正式で、真面目で、専門的な方法で書かれている場合があります。

XNUMXつの異なる声で書かれた同じメッセージ：

• 楽しさ： 「ソーシャルネットワークを拡大し、現在のトレンドを常に把握してください。」
• 深刻： 「最大のソーシャルネットワーキングアプリとオンライン求人市場のXNUMXつで仕事を見つけましょう。」

見下すような、不快な、専門的でないメッセージを誤って書くことは珍しいことではありません。 これはどこです トーン 戦場に出ます。 メッセージを声に出して読んでください、他の人に読んでもらい、句読点と文型を試してみてください。 それがあなたのトーンを磨く方法です。

別の考え方があります。あなたの声は決して変わらないが、あなたの口調は変わる。 あなたの声はあなたが人として誰であるかに似ていますが、トーンは与えられた状況であなたがどのように反応するかです。

能動態と受動態

文には常に俳優、動詞、ターゲットが含まれます。 これらが来る順序によって、文が受動態で書かれているか受動態で書かれているかが決まります。

俳優が最初に来る 能動的な声。 例：「CSSが背景をペイントします。」

能動態を使用する文は、対応する文よりも簡単です。 それらはより明確で、より短く、より理解しやすく、要点をまっすぐに理解するより専門的な声に最適です。

ととも​​に 受動態、俳優が最後に来ます。 （私がそこで何をしたかを見てください？）つまり、私たちのアクター（この場合はCSS）は、「背景はCSSによってペイントされています」のように最後に来ることを意味します。

読者は通常、頭の中で受動態を能動態に変換するため、処理時間が長くなります。 能動態で書く方が良いと聞いたことがあるなら、これが通常の理由です。 テクニカルライターは、研究を引用するなどの例外を除いて、ほとんどの場合能動態を好みます。

しかし、それはあなたが常に能動態のために努力しなければならないという意味ではありません。 同じ段落であっても、一方から他方に切り替えると、効果的に使用すれば、コンテンツがXNUMXつの文から別の文にシームレスに流れるようになります。

間違いを避ける

文法は言語の構造と正確さのすべてであり、それを達成するために文書をすばやく校正することほど良いことはありません。 綴りの間違い、文法の問題、意味の不完全さを書くことを取り除くことは非常に重要です。

この記事の最後に、専門家が書き間違いを避けるために使用する非常に貴重なツールを紹介します。 明らかに、最近ではほとんどすべてにスペルチェッカーが組み込まれています。 私たちのコードエディタには、間違いを防ぐのに役立つスペルチェックプラグインとリンティングプラグインもあります。 

しかし、すべてのものの文法のためのワンストップツールを探しているなら、 文法 最も広く使用されているツールのXNUMXつです。 私はそれか何かのリベートを得ていません。 これは、多くの編集者やライターがクリーンでクリアなコンテンツを作成するために使用する非常に優れたツールです。これは、Emmet、eslint、またはその他のリンターを使用してクリーンでクリアなコードを作成する方法と似ています。

コードコメントを書く

私たちが他の開発者のために書くことは、私たちがコードに書くもの、コードを説明する方法、またはコードの一部にフィードバックを与える方法など、私たちの仕事の全体的な品質に大きな影響を与える可能性があります。

すべてのプログラミング言語に、コメントを書き込むための標準的な機能セットが付属しているのは興味深いことです。 彼らはコードが何をしているのかを説明する必要があります。 それによって、私はこのような漠然としたコメントを意味するのではありません：

red *= 1.2 // Multiply `red` by 1.2 and re-assign it

代わりに、より多くの情報を提供するコメントを使用してください。

red *= 1.2 // Apply a 'reddish' effect to the image

それはすべてコンテキストに関するものです。 「私はどのようなプログラムを構築していますか？」 まさにあなたが自分自身に問うべき種類の質問です。

コメントは価値を追加する必要があります

「良い」コードコメントを作成するものを見る前に、怠惰なコメントのXNUMXつの例を次に示します。

const age = 32 // Initialize `age` to 32

filter: blur(32px); /* Create a blur effect with a 32px radius */

コメントの目的は、コードの一部に価値を付加することであり、それを繰り返すことではないことを忘れないでください。 それができない場合は、コードをそのままにしておくことをお勧めします。 これらの例を「怠惰」にしているのは、コードが明らかに行っていることを単に言い換えているだけです。 この場合、コメントは私たちがすでに知っていることを教えてくれるので冗長です—それらは付加価値ではありません！

コメントは現在のコードを反映する必要があります

古くなったコメントは、大規模なプロジェクトでは珍しいことではありません。 あえて言う 最も プロジェクト。

プログラマーであり、たむろする万能のクールな男であるデビッドを想像してみましょう。 Davidは、文字列のリストをAからZのアルファベット順に並べ替えたいので、JavaScriptで明白に行います。

cities = sortWords(cities) // sort cities from A to Z

次に、Davidは、sortWords（）が実際にリストをZからAにソートすることに気付きます。出力を単純に逆にすることができるため、これは問題ではありません。

cities = sortWords(cities) // sort cities from A to Z
cities = reverse(cities)

残念ながら、Davidはコードコメントを更新しませんでした。

今、私があなたにこの話をしなかったと想像してください、そしてあなたが見たのは上記のコードだけでした。 当然のことながら、コードのXNUMX行目を実行すると、「都市」はZからAに並べ替えられると思います。 この全体的な混乱の大失敗は、古いコメントによって引き起こされました。

これは誇張された例かもしれませんが、締め切りに間に合わない場合は、同様のことが起こる可能性があります（多くの場合、起こります）。 ありがたいことに、これはXNUMXつの簡単なルールに従うことで防ぐことができます… コードを変更すると同時にコメントを変更します。

これは、あなたとあなたのチームを多くのことから救う簡単なルールのXNUMXつです。 技術的負債.

不十分に書かれたコメントがどのように見えるかがわかったので、いくつかの良い例を見てみましょう。

コメントはユニディオマティックコードを説明する必要があります

時には、 ナチュラル 物事のやり方は正しくありません。 プログラマーは標準を少し「破る」必要があるかもしれませんが、そうするときは、その理論的根拠を説明する小さなコメントを残すことをお勧めします。

 function addSetEntry(set, value) {    
  /* Don't return `set.add` because it's not chainable in IE 11. */  
  set.add(value);
  return set;
}

助かりますよね？ このコードをレビューする責任がある場合は、何が起きているのかを説明するコメントなしで修正したいと思うかもしれません。

コメントで将来のタスクを特定できます

コメントを扱うもうXNUMXつの便利なことは、やるべきことがもっとあることを認めることです。

// TODO: use a more efficient algorithm
linearSort(ids)

このように、あなたはあなたの流れに集中し続けることができます。 そして後日、あなた（または他の誰か）が戻ってきてそれを修正することができます。

コメントはソースにリンクできます

つまり、StackOverflowで問題の解決策を見つけただけです。 そのコードをコピーして貼り付けた後、後で参照できるように、役立つ回答へのリンクを保持しておくとよい場合があります。

// Adds handling for legacy browsers
// https://stackoverflow.com/a/XXXXXXX

ソリューションは変わる可能性があるため、これは重要です。 コードが壊れた場合に備えて、コードがどこから来たのかを知ることは常に良いことです。

プルリクエストの作成

プルリクエスト (PRs）プロジェクトの基本的な側面です。 それらはコードレビューの中心に位置しています。 また、コードレビューは、適切な表現がなくても、チームのパフォーマンスのボトルネックになる可能性があります。

良い PR 説明の要約 何 変更が行われ、 なぜ それは作られています。 大規模なプロジェクトには、プルリクエストテンプレートがあります。 実際の例:

## Proposed changes
Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.

## Types of changes
What types of changes does your code introduce to Appium?
 - [ ] Bugfix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - ...

## Checklist
 - [ ] I have read the CONTRIBUTING doc
 - [ ] I have signed the CLA
 - [ ] Lint and unit tests pass locally with my changes

## Further comments
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc…

漠然としたことは避けてください PR タイトル

次のようなタイトルは避けてください。

• ビルドを修正します。
• バグを修正。
• パッチを追加します。

これらもしません 試み 私たちが扱っているビルド、バグ、またはパッチを説明するため。 ビルドのどの部分が修正されたか、どのバグが潰されたか、またはどのパッチが追加されたかについての少しの追加の詳細は、同僚とのより良いコミュニケーションとコラボレーションを確立するのに大いに役立ちます。 それはレベルセットし、同じページに人々を連れて行きます。

PR タイトルは伝統的にで書かれています 命令型の緊張。 それらは全体のXNUMX行の要約です PR、そして彼らは説明する必要があります 何 によって行われています PR.

いくつかの良い例を次に示します。

• NgOptimizedImageでカスタムsrcset属性をサポートする
• 75％の画質へのデフォルトの画像設定
• すべての組み込みControlValueAccessorsの明示的なセレクターを追加します

長く避けてください PRs

大 PR 巨大な説明を意味し、何百行または何千行ものコードをレビューしたいと思う人は誰もいません。

代わりに、次のことができます。

• を通じてチームとコミュニケーションをとる 問題,
• 計画を立てる、
• 問題を細かく分割するか、
• 独自の部分で個別に作業する PR.

今はもっときれいではないですか？

詳細を PR ボディ

異なり、 PR タイトル、本体は 　 以下を含むすべての詳細のための場所：

• なぜですか？ PR 行われていますか？
• なぜこれが最善のアプローチなのですか？
• アプローチの欠点、および可能であればそれらを解決するためのアイデア
• バグまたはチケット番号、ベンチマーク結果など。

バグの報告

バグレポートは、プロジェクトの最も重要な側面のXNUMXつです。 そして、すべての優れたプロジェクトは、ユーザーのフィードバックに基づいて構築されています。 通常、数え切れないほどのテストを行った後でも、ほとんどのバグを見つけるのはユーザーです。 ユーザーは優れた理想主義者でもあり、機能のアイデアを持っていることもあります。 聞いてください！

技術プロジェクトの場合、これらすべては問題を報告することによって行われます。 よく書かれた問題は、別の開発者が見つけて対応するのが簡単です。

たとえば、ほとんどの大規模なプロジェクトには テンプレート:

 <!-- Modified from angular-translate/angular-translate -->
 ### Subject of the issue
 Describe your issue here.

 ### Your environment
 * version of angular-translate
 * version of angular
 * which browser and its version

 ### Steps to reproduce
 Tell us how to reproduce this issue.

 ### Expected behavior
 Tell us what should happen.

 ### Actual behavior
 Tell us what happens instead.

スクリーンショットを収集する

を使用して問題をキャプチャします システムのスクリーン撮影ユーティリティ.

のスクリーンショットの場合 CLI プログラムでは、テキストが明確であることを確認してください。 それが UI プログラムでは、スクリーンショットが正しい要素と状態をキャプチャしていることを確認してください。

問題を実証するために、実際のやり取りをキャプチャする必要がある場合があります。 その場合は、 画面記録ツールを使用してGIFを記録する.

問題を再現する方法

プログラマーにとって、バグが自分のコンピューター上にある場合、バグを解決するのははるかに簡単です。 そのため、問題を正確に再現するための手順を実行する必要があります。

次に例を示します：

Update: you can actually reproduce this error with objects:

 ```html
 <div *ngFor="let value of objs; let i = index">
   <input [ngModel]="objs[i].v" (ngModelChange)="setObj(i, $event)" />
 </div>
 ```

 ```js
 export class OneComponent {
   obj = {v: '0'};
   objs = [this.obj, this.obj, this.obj, this.obj];
 ​
  setObj(i: number, value: string) {
     this.objs[i] = {v: value};
  }
 }
 ```

 The bug is reproducible as long as the trackBy function returns the same value for any two entries in the array. So weird behavior can occur with any duplicate values.

原因を提案する

あなたがバグを見つけたので、おそらくそれがそこにある理由のいくつかの潜在的な原因を提案することができます。 バグは特定のイベントに遭遇した後にのみ発生するか、モバイルでのみ発生する可能性があります。

また、コードベースを調べて、問題の原因を特定することも害にはなりません。 その後、あなたの問題ははるかに迅速にクローズされ、あなたは関連するものに割り当てられる可能性があります PR.

クライアントとのコミュニケーション

あなたはソロのフリーランサーとして働いているかもしれませんし、あるいはあなたは小さなチームの主任開発者かもしれません。 いずれの場合も、プロジェクトでクライアントとやり取りする責任があるとしましょう。 

さて、プログラマーの固定観念は、私たちが貧弱なコミュニケーターであるということです。 私たちは、過度に専門的な専門用語を使用し、他の人に何が可能で何が不可能かを伝え、誰かが私たちのアプローチに疑問を抱くと防御的になることさえ知られています。

では、そのステレオタイプをどのように軽減するのでしょうか。 クライアントに何が欲しいかを尋ね、常に彼らのフィードバックに耳を傾けます。 その方法は次のとおりです。

適切な質問をする

あなたとクライアントが同じページにいることを確認することから始めます：

• あなたのターゲットオーディエンスは誰ですか？
• サイトの目的は何ですか？
• あなたの最も近い競争相手は誰ですか、そして彼らは何を正しくやっていますか？

質問をすることは、特にクライアントのフィードバックや決定に同意できない状況で、前向きに書くための良い方法でもあります。 質問をすることは、あなたがあなた自身の立場を擁護することによって彼らを攻撃するのではなく、その人に彼ら自身の主張を支持することを強制します：

• 追加のパフォーマンスコストがかかっても大丈夫ですか？
• コンポーネントを移動することで、目的をよりよく達成できますか？
• 素晴らしい、発売後にそれを維持する責任があるのは誰ですか？ 
• これらのXNUMXつの色のコントラストがWCAGAA基準に合格するかどうか、手に負えないことを知っていますか？

質問ははるかに無実であり、敵意よりも好奇心を促進します。

自分を売る

あなたが見込み客に売り込みをしているなら、あなたは彼らにあなたを雇うように説得する必要があるでしょう。 なぜクライアントはあなたを選ぶべきですか？ 以下を指定することが重要です。

• あなたは誰ですか
• あなたがすること
• なぜあなたはその仕事にぴったりなのか
• あなたが行った関連する仕事へのリンク

そして、仕事に就いて契約書を作成する必要が生じたら、法律用語の束ほど威圧的なコンテンツはないことを忘れないでください。 デザインプロジェクト向けに書かれていますが、 契約キラー より親しみやすいものを書くための良い出発点になることができます。

あなたの細部への注意は、あなたと同じプロジェクトを勝ち取ろうとしている別の開発者との違いかもしれません。 私の経験では、クライアントは、技術的に最も有能で経験豊富な開発者よりも、一緒に仕事を楽しむことができると思う開発者を簡単に雇うでしょう。

マイクロコピーを書く

マイクロコピー ユーザーフレンドリーな書き方です UI エラーなどのメッセージ。 起動時までずっとバックバーナーに置かれていたため、開発者としてのあなたがエラーメッセージを書かなければならなかったことがあったに違いありません。

そのため、次のようなエラーが発生することがあります。

Error: Unexpected input (Code 693)

エラーは、ユーザーに対処してもらいたい最後のことです。 しかし、それらは実際に起こり、それについて私たちにできることは何もありません。 マイクロコピーのスキルを向上させるためのヒントをいくつか紹介します。

専門用語は避けてください

ほとんどの人はサーバーが何であるかを知りませんが、プログラマーの100％は知っています。 そのため、エラーメッセージに次のような珍しい用語が書かれているのを見るのは珍しいことではありません。 API または「タイムアウト実行」。

テクニカルクライアントまたはユーザーベースを扱っている場合を除いて、ほとんどのユーザーはコンピュータサイエンスのコースを受講しておらず、インターネットがどのように機能するのか、特定のものが機能しない理由を知らない可能性があります。 したがって、エラー。

したがって、良いエラーメッセージは説明すべきではありません なぜ そのような説明には恐ろしい専門用語を使用する必要があるかもしれないので、何かがうまくいかなかった。 そのため、専門用語の使用を避けることが非常に重要です。

ユーザーを責めないでください

これを想像してみてください：私はあなたのプラットフォームにログインしようとしています。 だから私は私のブラウザを開き、あなたのウェブサイトにアクセスして、私の詳細を入力します。 それから私は言われます：「あなたの電子メール/パスワードは間違っています。」

このメッセージは敵対的だと思うのは劇的に思えますが、無意識のうちにバカになります。 マイクロコピーは、ユーザーを責めることは決して大丈夫ではないと言っています。 Mailchimpのログインを基にしたこの例のように、メッセージを指先のないものに変更してみてください。「申し訳ありませんが、その電子メールとパスワードの組み合わせは正しくありません。 アカウントの復旧をお手伝いします。」

また、すべて大文字と感嘆符を避けることの重要性を追加したいと思います。 確かに、それらは興奮を伝えるために使用できますが、マイクロコピーでは、ユーザーに対する敵意の感覚を生み出します。

ユーザーを圧倒しないでください

マイクロコピーでユーモアを使うのは良い考えです！ それは気分を明るくすることができ、最悪のエラーによってさえ引き起こされる否定性を抑える簡単な方法です。

しかし、あなたがそれを使わないなら 完璧に、それはユーザーを軽蔑し、侮辱するものとして出くわす可能性があります。 それはただ ビッグ 取るリスク。

Mailchimpはそれをよく言います：

[D]冗談を言うために邪魔をしないでください—強制的なユーモアはまったくないよりも悪い場合があります。 よくわからない場合は、顔を真っ直ぐにしてください.

（強調鉱山）

アクセス可能なマークアップを書く

アクセシビリティとそれがテクニカルライティングにどのように関連しているかについての記事全体を簡単に使うことができます。 ちなみに、アクセシビリティは、コンテンツスタイルガイドに含まれていることがよくあります。 Microsoft & Mailchimp.

あなたは開発者であり、おそらくすでにアクセシビリティについて多くのことを知っています。 あなたは、アクセシビリティをワークフローのコア部分にする、より勤勉な開発者のXNUMX人でさえあるかもしれません。 それでも、すべての機能を含むアクセシブルなオンラインエクスペリエンスを実現することがどれほど重要であるかを私たち全員が知っているとしても、アクセシビリティの考慮事項が後回しにされる頻度は驚くべきものです。

したがって、他の誰かのコピーライティングをコードに実装したり、他の開発者向けのドキュメントを書いたり、さらには UI テクニカルライティングに関する他のすべてのアドバイスをまとめているので、自分自身をコピーし、いくつかの基本的なアクセシビリティのベストプラクティスに注意してください。

次のようなもの：

アンディベルは比較的いくつかを提供しています コンテンツをよりアクセシブルにするためにできる小さなこと、そしてそれらをチェックするのはあなたの時間の価値があります。 そして、キックのためだけに、 John Rheaは、いくつかの巧妙な編集トリックを披露します これは、セマンティックHTML要素を使用しているときに可能です。

まとめ

これらは、テクニカルライティングと開発がどのように一致するかを示すXNUMXつの方法でした。 例やアドバイスはロケット科学ではないかもしれませんが、他の開発者とのコラボレーション、自分の作業の維持、ピンチで自分のコピーを作成する必要がある、プロジェクトの提案を作成するなど、役立つことを願っています。もの。

結論：あなたのライティングスキルを磨き、あなたのライティングに少し余分な努力を払うことは、実際にあなたをより良い開発者にすることができます。

テクニカルライティングリソース

テクニカルライティングに興味がある場合：

コピーライティングに興味がある場合：

マイクロコピーに興味がある場合：

あなたがあなたの文章を改善するためにプロのスタイルガイドを使うことに興味があるなら：

アクセシビリティのための執筆に興味がある場合：