1,181 測定値

ソフトウェア開発者の皆さん、なぜまだテクニカルライティングを始めていないのですか?

に Ankur Tyagi12m2023/10/20

長すぎる; 読むには

何かについて教えたり書いたりすることは、それについて学ぶための最良の方法であり、新しいライフスタイルを始めるのに簡単にできる成果です。

featured image - ソフトウェア開発者の皆さん、なぜまだテクニカルライティングを始めていないのですか?

‘a programmer typing on his keyboard’ Image created by HackerNoon AI Image Generator

ブログは、あなただけでなく、テクノロジー業界の他のソフトウェア開発者にとっても、さまざまな理由から有用な部分です。

テクニカルライティングは、ソフトウェア開発者がソフトウェアエンジニアリングの他のソフトウェア開発者と技術的な知識/経験を共有するのに役立ちます。

テクニカルライティングは、特定のタスクを実行したり特定の目標を達成したりするために、複雑な情報を必要とする人に伝達することを含む文章作成の分野です。このため、テクニカルライティングは「複雑なことを単純化すること」と定義されることがよくあります。

また、書いているトピックの理解を深め、技術的な専門知識を明確に示します。

テクニカルライティングの最もユニークな点は、将来の素晴らしい機会 (テクノロジー分野でのリモートの仕事、フリーランスの執筆契約、大手テクノロジー企業の Web サイトでのゲスト投稿の機会など) を生み出すことができるだけでなく、オンラインでの存在は、最終的にはソフトウェア開発者としてのキャリアに役立ちます。

特定のトピックに関する情報を探すときに、時々自分のブログ投稿を読み返します。

ソフトウェアエンジニアリングのキャリアの中で何か興味深いことをしたのに、それを内緒にしていたとしたら、大きなチャンスを逃していることになります。
書き始めると、インターネット上で自分のアイデアを宣伝する効果的な方法になります。
「いつ見つけたらよかったかブログを書いてください… https://t.co/PcXR0fL9QF
— Ankur💻🎧💪 (@TheAnkurTyagi) 2023年10月3日

また、他の人が学ぶのを手伝うのが好き、オープンソースプロジェクトに参加して他の人に参加方法を教えるのが好き、または複雑なアイデアを文章を通じて分かりやすい方法で説明することに満足している場合、テクニカルライティングは次のような人に最適です。あなた。

この記事では、プログラミングとライティングをどのように融合させて開発者のスキルを向上させることができるかを説明することを目的としています。はい、書いてます！私たちは皆、ある程度の文章を書く能力を持っていると本気で思っています。私は、あなたがより熟練した開発者およびコミュニケーターになるために役立つ、ライティングのヒント、アドバイス、例を提供するためにここにいます。

テクニカルライティングとは

テクニカルライティングとは、ユーザー、開発者仲間、マネージャーが技術的な製品や技術的なスキルやアイデアを理解できるように、明確かつ詳細な指示を与えることです。

テクニカルライターは、これらのチュートリアルや技術ドキュメントを作成する人です。

テクニカルライティングには次のようなものがあります。

ユーザーガイドまたは2 つの技術的な SaaS間の統合方法
オンラインサポート記事
多くの場合、研究や実験を実施した後に、特定のトピックに関する情報を提示する技術レポート。科学および工学分野では一般的です。
技術提案書: これらの文書は、計画、アイデア、またはプロジェクトの概要を明確かつ説得力を持って説明します。これらは、承認、資金提供、または協力を求めるために使用されます。
プログラマ向けの内部メタマテリアルと開発者向けのAPI ドキュメント。

基本的に、テクニカルライターは、読者がその情報を特定の目的に効果的に適用できるような方法で技術的な詳細を伝えます。

テクニカルライティングを始めて、ソフトウェア開発/プログラミング、またはテクノロジーで学んだことについて書こうとしているが、まだ最初のブログを書いていない場合は、この記事の最初の 2 つのセクションに最大の価値があることがわかります。このブログ投稿では、テクニカルライターまたはブロガーとしての始め方と、ブログをスケールする方法について説明します。

ブログの残りの部分は、ソフトウェア開発者ライターとして成功し、職場で成功してキャリアアップするために必要な知識のギャップを埋めるのに役立ちます。

「夢があるなら、一生かけて勉強し、計画し、その準備をすることができます。あなたがすべきことは始めることです。」
—ドリュー・ヒューストン

書くことはどこにでもありますか?

人々がコードの学習に使用するオンラインリソースのトップ 2 は技術ドキュメントとスタックオーバーフローで、トップ 3 はブログで決まります。

人々がテクノロジーについて独学できるようにするための 3 つの条件には、明確なドキュメント、ソリューションを提供する活気に満ちたコミュニティ、頻繁な投稿が含まれます。

開発者は、ハウツービデオ、書かれたチュートリアル、書籍、フォーラムなど、幅広い追加ソースを重視し、自分たちの学習スタイルに最も適したソースと形式をまとめます。

多くの開発者にとって、チーム内やオンラインでアイデアを明確に表現できることは貴重なスキルです。コードの作成を含まないライティングを毎日どれだけ行っているか考えてみてください。このスキルは超能力です。

Slack チャット、電子メール、内部開発者ドキュメント、RCA ドラフト、Readme、コードコメント、Git コミットメッセージ、プルリクエスト、コードレビューコメント、年次パフォーマンスフィードバック、会議メモなど、さまざまな形式の執筆に従事します。

ソフトウェア開発者にとって、ライティングをマスターすることは非常に重要です。ライティングスキルが不十分だと、ある時点を超えるとキャリアアップが妨げられる可能性があります。多くのエンジニアは、キャリアの後半になって「ソフトスキルはコードと同じくらい重要である」ことに気づきます。

若者: 毎日 30 分間執筆を開始し、毎月 2 ～ 3 つのブログをオンラインに投稿すれば、ソフトウェアエンジニアリングのキャリアは大幅に向上し、将来テクノロジー分野でより良い機会を得ることができます。しかし、実際にこれを長期間にわたって実行できる開発者はほとんどいません。長期。 https://t.co/damIJ5gXys
— Ankur💻🎧💪 (@TheAnkurTyagi) 2023年10月4日

開発者にとってライティングが重要な理由

JavaScript、TypeScript、PHP、Go、Java — 世の中には非常に多くの異なるプログラミング言語があり、それらの多くを流暢に扱えるかもしれません。

技術者としてのキャリアにおいて、より高品質なコードを作成しようと努めるにつれて、日常言語で効果的に記述しコミュニケーションする能力は重要なスキルになりますが、ソフトウェアエンジニアリングの分野では過小評価される可能性があります。

ソフトウェアエンジニアリングはコードだけを扱うものではありません。それは人 + コードに関するものです。
ソフトウェアエンジニアとしてより良いライターになるには

エンジニアがコードについての考えをどのように明確にするかは、コード自体と同じくらい重要です。この問題に関するあなたの立場に関係なく、私たちの言葉には規範の有効性を高めるか妨げる力があることを全員一致で認めることができます。

書くことで運の表面積を増やすことができます。

L = D * T、ここで、L は運、D は実行、T は伝えることを表します。
– ジェイソン・C・ロバーツ

テクニカルライティングの 6 つの主な利点

概念をより深いレベルで理解するのに役立ちます。

説明している概念について調べる必要があるため、さまざまなアイデア、応用例、注意点がわかります。
他の人に説明すると、その概念がよりよく脳に定着します。
情報を構造化して他の人に提示すると、自分の知識のギャップが見つかることがよくあります。結果として、開発者としてのキャリアをより早く進歩させることにも役立ちます。
テクニカルライターは、新しいテクニカルブログを調査して執筆するたびに、そのテーマの専門家になるため、生涯学習者です。
書くことで、ユーザーの共感についての理解も深まります。自分の視点だけに頼るのではなく、読者や製品ユーザーの視点や感情にもっと焦点を当てるように促します。
その他の利点は次のとおりです。

さらに、さまざまな団体に貢献することでテクニカルライターとして収入を得ることができます。これらのAwesome-Companies-Who-Pay-Technical-Writersをチェックしてください。

大学では、ホステルで他の人に家庭教師をして勉強しました

何かを説明したり、そのふりをしたりすると、知識を一貫して整理する必要が生じ、知識のギャップが明らかになり、知っている部分が強化されます。

学ぶための最良の方法は教えることであり、書くことはすべての開発者にとって大きな資産となります。

ただ注意を払うのではなく、人々や企業があなたに報いてくれるのです。技術的なブログ投稿を書くと、即座にフィードバックを受け取ります。テクニカルライティングは情報を広めるのにも役立ち、さらに興味深い機会への扉が開かれます。

気に入れば、テクニカルライティングの分野で儲かるキャリアもあります。最近私がブログに書いていることのほとんどは、私が理解を深めようとしている概念です。文章で説明できないと、正しく理解できていないことになります。

テクニカルライティングの例にはどのようなものがありますか?

テクニカルライターとしてのあなたの役割には、複雑な技術情報をアクセスしやすくユーザーフレンドリーな言語に翻訳することが含まれます。テクニカルライティングには、段階的なチュートリアルや包括的なガイドの作成など、さまざまな形式が含まれます。

主な目標は、社内チームのメンバーであろうとエンドユーザーであろうと、製品やサービスの技術的側面の理解を促進することです。

このことを念頭に置いて、次のテクニカルライティングの例を読めば、明確に理解できるはずです。

SuperTokens レビュー – Auth0、Firebase Auth、AWS Cognito に代わるオープンソースの代替手段。

これは、スーパートークンのレビューの非常に単純な例であり、「スーパートークン」がユーザー認証に優れている理由を示しています。

Medusa を使用して Next.js E コマースストアを作成する方法

これは、アプリの構築と並行してチュートリアルを構築する方法を示す非常に良い例です。このブログでは、Shopify のオープンソース代替品である Medusa による e コマースストアを構築するためのステップバイステップガイドを共有しました。

MindsDB と OpenAI を使用して LLM をデプロイする方法

このガイドでは、MindDB と OpenAI を使用して LLM をデプロイする方法を共有しました。

データベースを Supabase から HarperDB に移行する方法

データベースを Supabase から HarperDB に移行する方法に関する完全なチュートリアル

5-製品ドキュメント

製品ドキュメントには、他の開発者ツールを効果的に使用し、統合するための手順が含まれています。

製品ドキュメントを作成するには、優れたテクニカルライティングスキルと組織の知識が必要です。これらはテクニカルライティングに該当するほんの一例であり、調査、視覚化、さまざまな聴衆とつながる能力などの高度なスキルが必要です。

ヒント - 「『タイトルは読者の興味を引くか』と自問してください。」もしそうなら、彼らはおそらく導入部分を詳しく調べてから、「この部分全体に時間を投資する価値があるか?」と判断するでしょう。技術的な投稿で私がよく観察するよくある間違いの 1 つは、紹介が多すぎること、または逆に紹介が少なすぎることです。

正確に作成された段落は、技術的なブログ投稿の準備を効果的に整えることができます。

テクニカルライターとして始めるにはどうすればよいですか

「テクニカルライティングやブログ」に関して私が受ける最も一般的な質問は、どうやって始めればよいかというものです。

人生において、何かをしてなりたいものになるための最大の障害は、始めることのようです。

最大の敵は「自信喪失」です。 pic.twitter.com/fw1691QRSY
— Ankur💻🎧💪 (@TheAnkurTyagi) 2023年8月10日

新しいトレーニングを開始する場合でも、マラソンのトレーニングを開始する場合でも、起業する場合でも、本を書く場合でも、さらに具体的に言うと、この場合は執筆する場合でも、最も難しいのは常に始めることです。

何をすべきかを議論するのに数え切れないほどの時間を費やしてしまうのは簡単であり、誘惑に駆られます。

「書く」ことを始めるよりも「読む」「読む」「勉強する」ほうがずっと簡単です。

しかし、秘訣は、一度に 1 つのステップだけを実行すればよいということです。

ソフトウェアエンジニアリングのキャリアで少なくとも 1 つの複合資産を構築する

– ブログを開始する – ニュースレターを開始する – YT 動画の録画を開始する – ポッドキャストを開始する – ネットワークの構築を開始する
構築、公開、繰り返し
将来のチャンスはインターネット上であなたを待っています
CC @TheAnkurTyagi
— Kap.ts (@Kaperskyguru) 2023年2月17日

そして周りを見回してください。ソフトウェアエンジニアリングのほとんどの開発者は、24 時間 365 日コードを書いているわけではありません。私たちのほとんどは、毎日他のことに多くの時間を費やしています。

これには以下が含まれます:

社内または顧客内のチーム全体で新しい機能をデモします。
製品の新しい機能または古い機能を文書化します。
JIRA チケット関連を更新します。
その新機能をサポートするためのバックログ作業を作成します。

もちろん、トイレや昼休み、 Twitter をスクロールする時間はいつでもあります 😉

だから考えすぎないで、ただ始めてください

「書くことはバスケットボールの遊び方を学ぶことに似ています。」
– デビッド・ペレル

ライターとして成功し、チャンスを見つけるには、3 つのスキルが必要です。

コーディング
書き込み
英語

はい、書き始める前に、まず時制、スペル、基本的な文法を含めて英語を理解する必要があります。

読者は、文法上の間違いや不適切な単語の選択が満載の記事を読みたくありません。

テクノロジー業界では、世界中のソフトウェア開発者、エンジニア、その他のテクノロジー専門家の間で英語がコミュニケーションに使用される事実上の言語となっています。ドキュメント、プログラミング言語、開発に使用されるツールに使用される言語です。

アイデアをシンプルかつ明確に伝える方法を学ぶ

技術的機能の実装方法を知っていても、そのプロセスを他の人に説明できるとは限りません。

良い教師になるには、共感力と、対象者に適した方法で情報を伝えるスキルが必要です

6歳児に説明できなければ理解できない。
アルバート・アインシュタイン

優れた作家になるための完璧な戦略はありません。それでは、なぜ私がこのトピックについて議論しているのか疑問に思うかもしれません。それは、最初からこの問題に対処することが重要だからです。

「戦略を探す必要はありません。文章の中で自分独自の意見を探し、自分のスタイルを構築してください。」

あなたが知っておくべき唯一のライティングハック。

テクノロジーは少ない方が良いので、私は 90% の時間 React を使用して作業しています。
初めて書く場合は、理解するためにもっと時間をかけてください。
下手なことを書いても構いません。
準備をやめて行動を始めましょう。

AI 時代に傑出した作家になる方法:
次のブログ投稿を書く前に、ChatGPT にそのトピックに関する記事を書いてもらい、インターネット上ですでに入手可能な一般的な内容を示してください。そうすることで、そのような発言を避け、読者にとって重要でユニークなものを書くことができます。
— Ankur💻🎧💪 (@TheAnkurTyagi) 2023年2月16日

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

読者は誰ですか?
彼らは Google で何を検索しますか、あるいはどのような問題に直面していますか?
彼らは現在どのブログを読んでいますか?
彼らはどうやって読んでいるでしょうか？

ブログ投稿のアイデアを思いつく方法

グーグルで頭を悩ませて何時間も費やす必要がないような記事を書きましょう。
何か新しいことを学んだときは、それをどのように学んだのか、何を学んだのかを書きましょう。
自分の分野、興味、職業についての話を書きます。
お気に入りのブロガーの楽しいと思ったブログ投稿を選択し、新しい視点から同じトピックを調査したり、同じような角度から別のテーマに取り組んだりできます。

何かをグーグルで検索したときに見つけたかったと思うブログ投稿を書きます。
— Ankur💻🎧💪 (@TheAnkurTyagi) 2023年3月20日

注 - ソフトウェアエンジニアリングのキャリアで何か興味深いことをしたのに、それを内緒にしていた場合は、大きなチャンスを逃していることになります。

自分のアイデアを効果的に宣伝するには、インターネット上で文章を書くのが最適です。

技術的な投稿やチュートリアルを書くのに最適な場所があります。まだそのことを学ぶ時間がない専門家向けに書き、彼らがすでに知っていることにリンクさせます。たとえば、jQuery を知っている人に最新の JS テクニックを説明するなどです。
— レイチェル・アンドリュー (@rachelandrew) 2019年2月20日

結論

ほとんどの熟練した開発者にとって、書き込みは簡単に実現できる成果です。

ブログ投稿を読むことでテクノロジーに関して多くのことを学べると思うなら、今週は一つ書いてみてください。
— Ankur💻🎧💪 (@TheAnkurTyagi) 2023年10月2日

すべての開発者がソフトウェアエンジニアリングで学んだことについてブログ記事を書くべき理由は、書くことで、もしかしたら自分が思っているほど何かを理解していなかったかもしれないということに気づくためです。

何かについて教えたり書いたりすることは、それについて学ぶための最良の方法であり、あなたがすでに直接の経験を持っているので、新しいライフスタイルを始めるのは簡単な成果です。したがって、あなたがしなければならないのは、参加して12のブログ投稿を書くことだけです今年の成果を評価し、次の行動を計画しましょう。