初心者のためのテクニカルライティング–技術ブログの基本へのAZガイド

あなたがライティングとテクノロジーを愛するなら、テクニカルライティングはあなたにとって適切なキャリアかもしれません。これは、テクノロジーが好きで、一日中コーディングをしたくない場合にできることでもあります。

テクニカルライティングは、他の人に教えたり、オープンソースプロジェクトに貢献したり、他の人にその方法を教えたりすることで学ぶのが好きな場合や、基本的に複雑な概念を簡単な方法で説明することを楽しんでいる場合にも役立ちます。

基礎を掘り下げて、テクニカルライティングを始めるときに知っておくべきことと考慮すべきことについて学びましょう。

目次

この記事では、以下について説明します。

  • テクニカルライティングとは
  • テクニカルライティングの利点
  • テクニカルライターとして必要なスキル
  • テクニカルライティングプロセス
  • 記事を公開するためのプラットフォーム
  • テクニカルライティングコース
  • テクニカルライティングフォーラムとコミュニティ
  • フォローするいくつかの素晴らしいテクニカルライター
  • 最後の言葉と参考文献

テクニカルライティングとは何ですか?

テクニカルライティングは、ユーザーが特定のスキルや製品を理解するのに役立つ詳細指向の指示を提供する技術です。

また、テクニカルライターは、これらの手順を作成する人であり、技術文書またはチュートリアルとも呼ばれます。これには、ユーザーマニュアル、オンラインサポート記事、またはコーダー/ API開発者向けの内部ドキュメントが含まれる場合があります。

テクニカルライターは、読者が意図した目的でその情報を使用できるように、技術情報を提示する方法で通信します。

テクニカルライティングの利点

テクニカルライターは生涯学習者です。仕事は単純でわかりやすい言葉で複雑な概念を伝えることを含むので、あなたはあなたが書いている分野に精通している必要があります。またはそれについて学ぶことをいとわない。

これは素晴らしいことです。なぜなら、あなたが研究して書く新しい技術文書ごとに、あなたはその主題の専門家になるからです。

テクニカルライティングはまた、ユーザーの共感をよりよく感じさせます。それはあなたがあなたが考えることよりも製品の読者やユーザーが感じることにもっと注意を払うのを助けます。

組織に貢献することで、テクニカルライターとしてお金を稼ぐこともできます。Smashing Magazine、AuthO、Twilio、Stack Overflowなど、彼らのために書くためにあなたにお金を払っているいくつかの組織があります。

これらすべてに加えて、オープンソースコミュニティに貢献したり、Google Season ofDocsやOutreachyなどの有料のオープンソースプログラムに参加したりできます。

また、フルタイムの職業としてテクニカルライティングを取り上げることもできます。多くの企業では、これらのスキルを持つ人が必要です。

テクニカルライターとして必要なスキル

適切な英語の使用を理解する

書くことを考える前に、英語、その時制、つづり、基本的な文法をよく理解する必要があります。あなたの読者は、間違った文法と貧弱な単語の選択でいっぱいの記事を読みたくありません。

物事を明確かつ簡単に説明する方法を知っている

機能の実装方法を知っているからといって、プロセスを他の人に明確に伝えることができるとは限りません。

良い教師になるためには、あなたは共感的であり、あなたの意図した聴衆に適した方法で用語を教えたり説明したりする能力を持っている必要があります。

6歳に説明できないと自分で理解できません。アルバート・アインシュタイン

いくつかのライティングスキルを持っている‌‌

私は作家は生まれるのではなく、作られていると信じています。そして、あなたは実際に書くことによってのみ書く方法を学ぶことができます。

あなたが紙にペンを置くまで、あなたはあなたが書くことがあなたの中にあることを決して知らないかもしれません。そして、あなたがいくつかのライティングスキルを持っているかどうかを知る唯一の方法があります、そしてそれは書くことです。

ですから、今日から書き始めることをお勧めします。このセクションにリストしたプラットフォームのいずれかから始めて、執筆の筋肉を伸ばすことができます。

そしてもちろん、技術分野での経験があることも大きなメリットです。

テクニカルライティングプロセス

あなたの読者が誰であるかを分析して理解する

あなたが技術的な記事を書いているときに考慮すべき最大の要因はあなたの意図された/期待される聴衆です。それは常にあなたの心の最前線にあるべきです。

優れたテクニカルライターは、読者のコンテキストに基づいて書き込みます。例として、初心者を対象とした記事を書いているとしましょう。彼らがすでに特定の概念を知っていると思い込まないことが重要です。

あなたは必要な前提条件を概説することによってあなたの記事を始めることができます。これにより、読者が記事に飛び込む前に必要な知識を確実に身に付けることができます(または習得できます)。

読者がクリックするだけで必要な情報を入手できるように、役立つリソースへのリンクを含めることもできます。

誰のために書いているのかを知るためには、誰がその文書を使用するかについて可能な限り多くの情報を収集する必要があります。

あなたの聴衆がその分野の専門知識を持っているかどうか、トピックが彼らにとって全く新しいかどうか、または彼らがその中間にあるかどうかを知ることは重要です。

あなたの読者も彼ら自身の期待とニーズを持っているでしょう。読者がドキュメントを読み始めたときに何を探しているのか、そして何が得られるのかを判断する必要があります。

読者を理解するために、書き始める前に次の質問を自問してください。

  • 私の読者は誰ですか?
  • 彼らは何が必要ですか?
  • 彼らはどこで読んでいますか?
  • 彼らはいつ読んでいますか?
  • なぜ彼らは読んでいるのでしょうか?
  • 彼らはどのように読んでいますか?

これらの質問は、あなたがあなたの文章を読んでいる間のあなたの読者の経験について考えるのにも役立ちます。それについてはこれからもっと話します。

ユーザーエクスペリエンスについて考える

技術文書では、ユーザーエクスペリエンスは、Web上のどこにでもあるのと同じくらい重要です。

オーディエンスとそのニーズがわかったので、ドキュメント自体がどのようにニーズに対応しているかを覚えておいてください。読者が実際にドキュメントをどのように使用するかを無視するのはとても簡単です。

執筆中は、読者であるかのように、継続的に戻ってドキュメントを表示します。自問してみてください:それはアクセス可能ですか?読者はそれをどのように使用しますか?彼らはいつそれを使うのでしょうか?ナビゲートは簡単ですか?

目標は、読者にとって有用であり、使用可能なドキュメントを作成することです。

ドキュメントを計画する

ユーザーが誰であるかを念頭に置いて、ドキュメントを概念化して計画することができます。

このプロセスにはいくつかのステップが含まれていますが、これについては後で説明します。

トピックについて徹底的な調査を実施する

あなたの文書を計画している間、あなたはあなたが書いているトピックを研究しなければなりません。あなたが消費し、より深い洞察を得るために、グーグルだけが離れて検索するたくさんのリソースがあります。

これは剽窃であるため、他の人の作品や記事を持ち上げて自分のものとして見送ろうとしないでください。むしろ、これらのリソースをあなたの仕事の参考資料やアイデアとして使用してください。

可能な限りグーグルで、研究ジャーナル、本、ニュースから事実と数字を入手し、あなたのトピックについてできるだけ多くの情報を収集してください。次に、アウトラインの作成を開始できます。

アウトラインを作成する

文書を拡張する前に文書の内容の概要を説明すると、より焦点を絞った方法で書くのに役立ちます。それはまたあなたがあなたの考えを整理しそしてあなたの執筆のためのあなたの目標を達成することを可能にします。

アウトラインは、読者にドキュメントから何を引き出してほしいかを特定するのにも役立ちます。そして最後に、それはあなたの執筆を完了するためのタイムラインを確立します。

関連するグラフィック/画像を取得する

アウトラインを作成すると、ドキュメントのさまざまなセクションに埋め込む必要のあるさまざまな仮想支援(インフォグラフィック、GIF、ビデオ、ツイート)を特定するのに非常に役立ちます。

また、これらの関連するグラフィックを手元に置いておけば、書き込みプロセスがはるかに簡単になります。

正しいスタイルで書く

最後に、あなたは書き始めることができます!これらの手順をすべて完了すると、書き込みがはるかに簡単になります。ただし、自分の文章スタイルが技術文書に適していることを確認する必要があります。

執筆は、アクセス可能で、直接的で、専門的である必要があります。花のようなまたは感情的なテキストは、技術文書では歓迎されません。このスタイルを維持するために、ここで育成する必要のあるいくつかの重要な特性を示します。

能動態を使用する

受動態よりも読みやすく理解しやすいため、記事では能動態を使用することをお勧めします。

能動態は、文の主語が動詞の動作を積極的に実行していることを意味します。受動態は、主語が動詞の動作の受信者であることを意味します。

受動態の例を次に示します。ドキュメントは、すべてのWeb開発者が年に6回読む必要があります。

そして、ここに能動態の例があります:すべてのウェブ開発者はこのドキュメントを年に6回読むべきです。

言葉を慎重に選ぶ

単語の選択は重要です。文脈に最適な単語を使用するようにしてください。読者が参照する名詞を特定するのが難しい場合があるため、「it」や「this」などの代名詞を使いすぎないようにしてください。

また、俗語や下品な言葉は避けてください。気質や文化的傾向が自分とは異なる可能性のある、より幅広い聴衆のために書いていることを忘れないでください。

過度の専門用語を避ける

あなたがあなたの分野の専門家であるならば、それが他の読者を混乱させるかもしれないことに気付かずにあなたが精通している専門用語を使うのは簡単かもしれません。

また、これまで説明していない頭字語の使用は避けてください。

ここに例があります:

あまり明確ではありません:PWAは本当にマルチプラットフォーム開発の未来と考えられています。AndroidとiOSの両方で利用できるため、将来のアプリになります。

改善:プログレッシブWebアプリケーション(PWA)は、まさにマルチプラットフォーム開発の未来です。AndroidとiOSの両方で利用できるため、PWAは将来のアプリになります。

平易な言葉を使う

使用する単語を減らし、読者がテキストを理解できるように書きます。‌‌長くて長い単語は避けてください。常に可能な限り明確な方法で概念と用語を説明するようにしてください。

ビジュアルフォーマット

テキストの壁は読みにくいです。視覚的表現が不十分なドキュメントでは、最も明確な指示でさえ失われる可能性があります。

彼らは絵は千の言葉の価値があると言います。これは、テクニカルライティングでも当てはまります。

しかし、技術文書に値する画像だけではありません。技術情報をテキストだけで伝えるのは難しい場合があります。適切に配置された画像または図は、説明を明確にすることができます。

ビジュアルも大好きなので、適切な場所に挿入すると便利です。以下の画像を検討してください。

まず、ビジュアルのないブログスニペットを次に示します。

これは同じブログのスニペットですが、ビジュアルが含まれています。

記事に画像を追加すると、コンテンツの関連性が高まり、理解しやすくなります。画像に加えて、必要に応じてgif、絵文字、埋め込み(ソーシャルメディア、コード)、コードスニペットを使用することもできます。

思いやりのあるフォーマット、テンプレート、画像や図も、読者にとってテキストをより役立つものにします。@Bolajiayodejiのテクニカルライティングテンプレートについては、以下のリファレンスを確認してください。

注意深いレビューを行う

どんなタイプの良い文章でも、スペルや文法の誤りがあってはなりません。これらのエラーは明白に思えるかもしれませんが、(特に長いドキュメントでは)それらを見つけるのは必ずしも簡単ではありません。

'publish'を押す前に、常にスペルを再確認してください(Isにドットを付け、Tsをクロスしてください)。

GrammarlyやHemingwayアプリなど、文法やスペルの誤りをチェックするために使用できる無料のツールがいくつかあります。記事の下書きを誰かと共有して、公開する前に校正することもできます。

記事を公開する場所

テクニカルライティングを始めることにしたので、ここに無料でテクニカルコンテンツを書き始めることができるいくつかの良いプラットフォームがあります。また、将来の雇用主がチェックアウトするための魅力的なポートフォリオを構築するのにも役立ちます。

Dev.toは、ライターとリーダーの両方が有意義に関与し、アイデアやリソースを共有することができる何千もの技術者のコミュニティです。

Hashnodeは、カスタムドメインマッピングやインタラクティブコミュニティなどのすばらしい特典を備えた、私の頼りになるブログプラットフォームです。このプラットフォームでブログを設定することも簡単で迅速です。

freeCodeCampには非常に大きなコミュニティと視聴者のリーチがあり、記事を公開するのに最適な場所です。ただし、以前のいくつかの執筆サンプルを使用して、出版物の執筆を申請する必要があります。

申請は承認または却下される可能性がありますが、落胆しないでください。良くなった後はいつでも再申請できますが、誰が知っていますか?あなたは受け入れられる可能性があります。

あなたが彼らのために書く場合、彼らはあなたが可能な限り最も洗練された記事を公開することを確実にするために、公開する前にあなたの記事をレビューして編集します。彼らはまた、より多くの人々がそれらを読むのを助けるために彼らのソーシャルメディアプラットフォームであなたの記事を共有します。

Hackernoonには7,000人を超えるライターがおり、コミュニティの20万人を超える毎日の読者に記事を公開するための優れたプラットフォームになる可能性があります。

Hacker Noonは、プラットフォームに公開する前に記事を校正することでライターをサポートし、よくある間違いを回避できるようにします。

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

他のすべての分野と同様に、テクニカルライティングにはさまざまなプロセス、ルール、ベストプラクティスなどがあります。

テクニカルライティングのコースを受講すると、学ぶ必要のあるすべてのことをガイドし、ライティングの旅を始めるための大きな自信を高めることができます。

チェックアウトできるテクニカルライティングコースは次のとおりです。

  • Googleテクニカルライティングコース(無料)
  • Udemyテクニカルライティングコース(有料)
  • Hashnodeテクニカルライティングブートキャンプ(無料)

テクニカルライティングフォーラムとコミュニティ

一人でできることはほとんどない、一緒にできることはたくさんある〜ヘレン・ケラー

あなたと同じ情熱を共有する人々と一緒にコミュニティやフォーラムに参加することは有益です。フィードバック、修正、ヒントを入手したり、コミュニティの他のライターからスタイルのヒントを学ぶこともできます。

参加できるコミュニティとフォーラムは次のとおりです。

  • ハッシュノード
  • Dev.to
  • テクニカルライティングの世界
  • テクニカルライターフォーラム
  • ドキュメントフォーラムを書く

フォローするいくつかの素晴らしいテクニカルライター

私のテクニカルライティングの旅では、ライティングの旅、一貫性、スタイルが私にインスピレーションを与えてくれる素晴らしいテクニカルライターを何人かフォローしました。

これらは私が尊敬し、テクニカルライティングの仮想メンターと見なしているライターです。時々、彼らは私が役に立ち、多くを学んだテクニカルライティングのヒントを落とします。

これらのライターの一部を次に示します(Twitterハンドルでハイパーリンクされています)。

  • クインシーラーソン
  • エディディオン・アシクポ
  • カタリンピット
  • ビクトリアロー
  • ボラジアヨデジ
  • アムルタ・ラナーデ
  • クリスボンジャーズ
  • コルビー・ファイオック

最後の言葉

テクニカルコンテンツの発行を開始するために、テクニカルライティングの学位は必要ありません。ポートフォリオを構築し、実践的な経験を積みながら、個人のブログや公開GitHubリポジトリに書き込みを開始できます。

本当に–書き始めるだけです。

既存のプログラムまたはプロジェクトの新しいドキュメントを作成して練習します。GitHubには、チェックアウトしてドキュメントに追加できるオープンソースプロジェクトが多数あります。

使いたいアプリはありますが、ドキュメントの記述が不十分ですか?あなた自身を書いて、フィードバックのためにそれをオンラインで共有してください。また、hashnodeでブログをすばやく設定して、書き始めることもできます。

あなたは書くことによって、そして作家がどのように彼らのキャラクターを作成し、彼らの物語を発明したかについて読んで考えることによって書くことを学びます。あなたが読者でないなら、作家になることさえ考えないでください。-ジーン・M・アウル

テクニカルライターは常に学んでいます。新しい主題分野に飛び込み、外部からのフィードバックを受け取ることで、優れた作家は自分たちの技術を磨くことを決してやめません。

もちろん、優れた作家は貪欲な読者でもあります。よく読まれている、または頻繁に使用されているドキュメントを確認することで、自分の文章が確実に向上します。

あなたの技術記事を見るのが待ちきれません!

参考文献

テクニカルライティング入門‌‌

技術記事の構成方法‌‌

あなたの聴衆、その理由と方法を理解する

‌‌テクニカルライティングテンプレート

これがお役に立てば幸いです。もしそうなら、Twitterで私をフォローして知らせてください!