00:06
8月19日金曜日、地獄朝9時を回りました。
今日の東京は良い天気なので、今日も暑くなる感じかなと思います。
はい、おはようございます。めめめのkeethこのくわはらです。
では、本日も朝から朝を始めていきたいと思います。
今日は何を読むかちょっと悩ましくて、いろいろ記事を見たんですけど、
だいたい画像とソースコード、オンパレードみたいな記事ばっかり多くてですね。
昨日みたいに結構抽象的な記事ばっかり読んでもちょっと面白くないなというところだったので悩ましかったんですけど、
今日はタイトルにある通り、ちょっと技術のネタではないんですけど、
我々デベロッパー向けの記事として、
テクニカルライティングフォーデベロッパーズですね。
という記事を読んでいこうかなと思います。
はい、もうタイトル通りですね。
テクニカルライティング、技術的な記事の書き方とかノウハウとかが多分期待でき、
書いてあるんだろうということを期待して読んでいこうかなと思います。
はい。
市中郵政さんですね。おはようございます。ご参加ありがとうございます。
ではでは、早速入っていきたいと思います。
HTML、CSS、JavaScript、Python、PHP、C++、Dart、ほげほげみたいななど非常に多くのプログラミング言語があり、
その中には完全に堪能なものもありますと。
しかし私たちがより良いコードを書こうとするにつれて、
私たちが日常的な言語で書いてコミュニケーションする方法はますます重要になってきています。
そしておそらく見落とされてさえ思いますと、
コードを記述する方法というのはコード自体と同じくらい重要です。
そしてあなたがこの戦場に落ちているにも関わらず、
私たちの言葉はコードの有効性を助けると同時に傷つける可能性があることにも誰もが同意することができます。
この記事ではこれらの一見異なる2つのフィールド、プログラミングとライティングですね。
組み合わせて開発者のスキルを次のレベルに引き上げる方法について解説していこうと思います。
で、ウエイトですね。ちょっと待ってくださいと。
テクニカルライティングっていうのはそもそも何ですかみたいなところですけど、
私たちはみんな何らかの意味で作家だと心から信じています。
ここでは開発者としてコミュニケーターとしても優れたアプリを作成するためのヒントやアドバイスで例を紹介していきたいなと思っていますということです。
面白いですね。
私たちはみんな何らかの意味で作家だというふうに心信じています。
これ僕は結構近い感覚があって、作家というふうに思いましたら、僕は結構哲学者だと思っています。
一局は僕らも開発者、デベロッパーなんですけど結局は思想があったりとか、いろんな考えがあったりとか主張があったりするので、
みんな自分なりの心の中に持っている哲学っていうのがあって、それに信じて言葉を発していったり、
アプリを作ったりとかいうところがあるんですね。
結局人間なのでそこをみんなやってるよねっていうのが僕の持論なんですけど。
この方は技術者としてみんな何かしらの作家だというふうに言ってますね。
03:02
この観点は結構面白いと思いました。
作家と言ってますけどみんな何か書いてるかというと難しいところですけど、
開発者はコードを書くんですけど、コード以外のところもしっかり書かなきゃいけないところはあるとは思うのでね。
その意味でみんなが何かしらの作家という言い方は逆に言うと書いてもいいんだというか、
心理的なハードルを下げるニュアンスもあるなというふうに聞こえましたね。
いきなり余談にどんどん入っちゃいそうなのでいきましょう。
テーブルオブコンテンツは飛ばして、一つ目ですね。
テクニカルライティングis everywhereってところに行きたいと思います。
昨年ですね、人気のMacのGitクライアントとかTowerの開発チームっていうのが
4,000人以上の開発者を対象に行った調査では、
その50%近くが1日に3時間もしくは6時間コードを書いていることが分かりました。
結構書いてるんですね。
海外の方なので世界的な調査だと思いますね。
一応その4,000人以上のディベロッパーへの調査を行ったっていうところですけど、
そこのもちろんリンクもありましたのでそれ見てみてもらえればと思います。
もちろん2021年の結果ですね。
ざーっと一応書いてますけども、
数字についての言及はそんなにされないですね。
ざっくり言うと、1時間未満が2.3%、1から2時間が6.2%、2,3時間が8.9%でここから増えてきますね。
3,4時間で14.5%、4,5時間で17.1%、5,6時間で18.1%でここがトップですね。
3,4時間から5,6時間を足してだいたい過半数いっているってことですね。
31.6%の、ギリギリいってないのか、49.7%の人たちが、約50%ですね確かに。
が3,4時間から5,6時間やってますと。
6,7時間で10.7%、7,8時間で11.1%で、8時間以上も11.1%いるっていうので結構多いですね。
考えると、日本のエンジニアってどうなんですかね。
行動書いてるんですかね。
わかんないですけど少なくとも弊社のエンジニアは行動書く時間がちょっと短いかもしれないですね。
そもそも勤務時間が短いっていうのはあるかもしれないです。
昨今日本の人たちの評価って海外に比べると全然仕事しないじゃんっていう風な統計データですね。
全体を見たときに日本人は海外に行くと比べて仕事をしてる量、絶対力が少ないっていう風に最近は言われてますね。
っていう風によく言われたりするので、その差もあると思いますね。
とはいえ8時間以上コード書いてるのが11%いるっていうのは結構すごい話だなと思いましたね。
とにかく日本の会議が多かったりとか、しっかりコミュニケーションを大事にして、
物事をしっかり決めていくっていうところを重きを置いたりするっていうのが日本の気質だったりする気がするので、
きっちり作る分その代わりにベロシティが下がるという別の問題はありますけど、
06:00
その結果、行動書く時間が減っているという気もしますけどね。
どっちが良い悪いかは議論の余地はありますが、結果としてビジネスのバリューが出していれるのであれば、
どちらでもいいと思いますが、少なくとも今回の数字だけでも見るとそれだけ海外の方はコードを書いてるよということでした。
ただまぁでも、3から5、6時間っていうのを見るとそんなに大差はないかなとも思いますね。
はい。すいませんね、戻ります。
続けて、確かにこれはかなりニッチなグループを対象にした一つの調査ではありますけど、
私たちの多くはその範囲内に入ると思います。
いずれにせよ、開発者っていうのは24時間365日コードを書いているわけではありません。
この世論調査が示すように、私たちは他のことに多くの時間を費やしているからです。
これらには次のものが含まれます。
新機能のデモをするとか、その新機能を文書化、ドキュメンテーションを書くとか、
新しい機能に関連する作業チケットの更新、またはその新機能をサポートするためのバックログの作業とか、
もちろんトイレ休憩とか、ワードルの時間もあったりします。
要は遊びの時間もありますよねってことですね。
いずれにせよ、私たちが通常行うことのほとんどっていうのは、
チームとか同僚クライアント、ユーザー、その他の開発者などのユーザーとのコミュニケーションに関連していますよね。
ですから私たちはかなりの時間をコードを使ったコンピューターとのコミュニケーションに加えて、
言葉を使った人間とのコミュニケーションに通しています。
言葉は書き言葉であります。
そしてもし私たちがもっと上手に言葉を書けば、私たちはもっと上手くコミュニケーションを取れるでしょうと。
コミュニケーションが上手くできれば、欲しいものを手に入れやすくなります。
これがテクニカルライティング101です。
101って言ってますけど、
これはバージョンの話なんですかね。ちょっとわからないですけど。
図があって、いわゆるベンズみたいな図がありますね。
テックライティングの○とコーディングの○っていうのが2つあります。
テックライティングの○の方は、
チュートリアルとかニュース、ブログ、データ、レビューとかがテックライティングですね。
次はコーディングですね。
クラッシー図、バリアブル図、シンタックス、ファンクション図、バージョンコントロールというのがコーディングの方の書くものですね。
その2つの図が重なっているところ、両方にまたがるものっていうのが、
マイクロコピーだったり、プロリクエストだったり、イシューだったり、コメントだったりとか、この辺ですね。
確かにこの辺は、ドキュメンテーションであり、コーディングでありっていうところもありますね。
両方含みますもんね。
特にプロリクエストは一番コミュニケーション、イシューもそうですね。
ちゃんとテクニカルライティングをしつつでもコミュニケーションをとるってところですよね。
この差、ちょっと議論の余地というか、いろいろ要素についてはふーんって思うところもありますが、
大筋そうだなというところもありますね。
続いていきましょう。
09:00
もちろん今言ったような図もありますけど、これだけじゃもちろんないですよと。
プログラマーの中には独自の製品を作るのが好きな人もいます。
つまりマーケティングを仕事の一部にする人もいます。
必要があります。
テクニカルライティングもそれに大きな役割を果たします。
だからテクニカルライティングとは、どこにでもあると言っても過言ではないというふうに思いますよと言っています。
そうですね。
マーケティングを仕事の一部にする必要がある。
結局は作ったプロダクトか製品を使ってもらわなきゃいけないので、
それを売り込む必要もあるので、そういうところがあるためにもテクニカルライティングはやっぱり大事だよねという話ですね。
続いて、What is good programmerが良いプログラマーとは何でしょうかというところに入っていきたいと思います。
プログラマーじゃなかったですね。
普通にグラマーでしたね。
良い文法とは何ですか。
失礼。
いきましょう。
世の中には非常に多くのプログラミング言語が存在するため、他の言語を学ぶことは絶対に避けたいことです。
文法は英語に不可欠な要素であり、コミュニケーションの可能性を最大限に引き出します。
それは私たちをよりフォーマルでプロフェッショナルで一貫性のあるものにします。
言語について簡単に説明しましょう。
例えばまず英語の公文ですね。
The English Syntax
プログラミング言語と同じように、英語には明確な公文があり、単語から始まります。
単語は英語の構成要素であり、8種類に分類されます。
一つの文章として、CSS is an elegant language for styling elements that is easily learned and taught, yet it is taught to master.
タフか。タフドゥマスターですね。
というような文章を型としましょう。
それを分解するとたくさんあって、ナウンズ・バーズ・エグザンプルとか、
エグザンプルをはじめますね。
ナンズとバーズとアドジェクティブズ・プリポジションズ・何たらかんたらと結構分解ができるわけですね。
いわゆる主語・動詞・目的語・何たらかんたらと分類ができるよという話ですね。
大きく8個に分類できます。
具体例も載せてますけど、それを読んでいくと長いので、
すみません、はじめます。
この辺はこの後ツイッターで流しますので、見てみてもらえればと思います。
続いてUIコンポーネントのようなものを考えてみましょう。
これらは完全で堅牢なUIを組み立てるのと同じように、
移動して完全で堅牢な文章を構築できるモジュール部分でもあります。
すべてのコンポーネントは常にそこにある必要がありますかとか、
そんでもないですね、そんなことはないですよと。
インターフェースの場合と同じように、
エクスペリエンスを完成させるために必要な要素を使用して文章を組み立てますと言ってます。
12:02
ちょっとそのUIコンポーネントの話を例にいたしましたけど、
全然移動はできますよねという話ですね。
ちなみに文章構成の話で言うと、
日本語の難しさの一つに、
言葉そのものが難しかったりとか、
ひらがな、カタカナ、漢字ってあって、
日本語って柔軟性がものすごく高いんですよ。
海外の言葉という言葉があるじゃないですか、海外の言語。
例えば何でしょうね。
例がありけど、最大値のMAXという英単語だとするじゃないですか。
普通は最大値というふうに略して、
日本語として僕らは理解していくんですけど、
一方でMAXという英単語をマックスというそのカタカナにして
僕らはインストールできちゃうんですよね。
なのでどんな外来語であっても、
一旦カタカナにしてしまえば、
僕らって自分らの言語としてインストールしちゃうんですよね。
ここが柔軟性の高さであり、
そのせいで難易度が上がっているみたいな主張もあったりするんですよね。
ところが日本語の難しさであり、
面白さではありますけどね。
そうやって日本っていうのは、
まず世界対戦後、
AIを負けたので、とにかく取り入れて取り入れて、
進化して対応していかなきゃいけないというところがあったので、
そういう文化がすごく根付いたと思いますね。
もちろんカタカナとか漢字平仮名は古来からずっとあったんですけど、
やっぱりあそこがすごい転換器だったんじゃないかとよく言われますね。
はい、余談でした。
もう一個そうだ、余談ついでにもう一個しゃべると、
日本語の難しさのもう一つって、
日本語って主語同士目で英語って、
英語だったらちゃんとSVOとかであるじゃないですか。
あるんですけど、日本語にもちゃんと一応あるんですけど、
日本語って全部をバラバラにしても意味通じちゃうんですよね。
例えば、私は今おにぎりが食べたいとか言うじゃないですか。
今、おにぎり、私は食べたいって言っても通じるじゃないですか。
日本語ってぐっちゃぐちゃにしても結局通じてしまうんで、
結局文法あると言いながら文法なくないみたいなので、
海外の人からすると本当によくわからんっていうことになるんですって。
ここがまたもう一個日本語の難しさだったりするらしいですね。
はい。
余談が過ぎたので戻ります。
はい、もう残り10分しかないので。
じゃあ戻りましょう。
続いてですね、ボイス&トーンですね。
声とトーンっていう話です。
語彙、句調点、文の構成、および単語の選択、
これらはすべて英語の材料です。
アイディアを共有したり、友人や家族とコミュニケーションを取ったり、
同僚にメールを送信したりするために使用します。
しかし私たちのメッセージのサウンドを考慮することが一つ重要になりますよと。
一つの簡単符でメッセージのトーンを完全に変えることができるっていうのは驚くべきことです。
英語って同じ単語なんですけど、コンテキストとか、
そのトーンで意味合いが全然変わるので、
全く通じ方が変わるっていうふうに言ったので、
ちゃんとトーンは気をつけてくださいって言われましたね。
すごいですよね。
トーンだけで意味を変えるっていうのはなかなか難しいというか、
脆い言語だとちょっと感じましたね。
15:03
それは逆に言うと、
しっかり気持ちを乗せられることができるという意味では、
なかなか興味深いなとも思いました。
続きもいきましょう。
例えばプログラミングが好きです。
プログラミングが好きで顔文字を付けますとか、
声とトーンを混同しやすく、その逆もありますよねっていうふうに言ってます。
単純に当店だけでプログラミングが好きですって書くと、
例えばビックリマーク付けるとか顔文字を付けたりすると、
全然伝わり方とか熱意が変わりますよね。
言葉の選択に関わるのは声であり、
それは文脈に依存します。
例えば初心者向けのチュートリアルでは、
親しみやすい声を伝えるために、
スラングやインフォーマルな言葉を使用することが多くなりますが、
ドキュメントは要点を明確にするために、
フォーマル、シリアス、プロフェッショナルな方法で
吸収される場合があります。
同じメッセージが2つの異なる声で書かれています。
文章を読んでいきましょう。
例えば楽しいってことですね。
ソーシャルネットワークを拡大して今のトレンドをアップデートしよう。
真面目な話ですね。
最大級のソーシャルネットワーキングアプリと
オンライン求人指標で仕事を見つけるみたいな、
2つの文章があったとします。
人を見下していて攻撃的でプロフェッショナルではないと思われるメッセージを
誤って書くことはもちろん珍しくありません。
ここでトーンが重要になります。
メッセージを声に出して読んだり、他の人に読んでもらったり、
苦闘点や文章構造を試してみてください。
そうやって誤調を磨いていくことが必要になりますよと。
別の言い方をすれば、声は変わらないが声のトーンは変わります。
声は人としてのあなたに似ていますが、
トーンは特定の状況での反応の仕方ですと言ってますね。
確かにおっしゃった通りですね。
声は変わらないのは確かにそうなんですけど、
声のトーン自体は変えることは確かにできるので、
そこで自分がどういうふうに感じていますかというのも表現することができますよね。
声って本当に実は表現力がものすごく高いんですよね。
もう一個雑談したかったので雑談を出します。
最近僕はコーチングを学んだからというところがあるんですけど、
昔のコーチングって今みたいにコロナが発生した際で、
今リモートでZoomだったりとかで顔の対面じゃないんですけど、
顔を出してコーチングとかされたりするんですけど、
昔のコーチングってもちろんZoomなんかあるわけないですし、
でもかといって遠方の人とコーチングをするという状況もあり得るんですよ。
どうやってやるかというとですね、
電話でコーチングしてたらしいんですよ。
相手の顔とか表情が全然見えなくて、
ひたすら話した声のトーンとか口調とかその辺だけで
コーチングを昔の方はされてたっていうので、
本当にすごいなと思いましたね。
すごいと思った反面、声ってそれだけ伝えることできるんだなっていうのもびっくりしました。
なので割と声って無視できないし、
今こうやってオンラインで何か喋ったりZoomミーティングするときにも、
やっぱりマイクのクオリティとか伝わる声とかのクオリティにこだわるっていうのは
18:02
結構大事なことかなって思いましたね。
はい。
とはいえ今僕がTwitterのスペースで配信している、
この配信で使っているピンマイクのクオリティが低くて、
自分で聞いといて自分でこの声微妙だなって思ったりしてますけどね。
ここはちょっと改善したいと思います。
はい。
じゃあ余談からまた戻ってきまして、
続いてはですね、
アクティブ&パッシブボイスですね。
はい。
いきましょう。
文には常にアクター、動詞、
動詞というよりも動詞ですね。
動詞及びターゲットが含まれます。
これらが来る順番によって文が受動態で書かれているか
濃度帯で書かれているかっていうのが
音声で書かれているかでも決まりますと。
例えばですね、その俳優はまず活発な声で登場します。
例えばですね、例。
例として、CSS Paint the Backgroundですね。
みたいな文章があります。
この文章がいきなりコアなんですかね。
アクターとして表現されるのはなかなか面白いですけど。
例えばそういう文章があったとしましょう。
CSS Paint the Backgroundですね。
はい。
動態を用いた文章というのは対応する文章よりも率直であります。
より明確で短く理解しやすくなっています。
担当職人のプロフェッショナルな声に最適ですよと。
逆に受け身の声では俳優というのが最後に来ます。
今さっき言うとアクターですね。
アクターというワードが最後に来ます。
俺が何をしたか分かるか?っていうクエスチョンですね。
つまりアクターですね。
この場合はCSSなんですけど、というのは最後になります。
次のようになりますよと。
はい。
The background is painted by CSSというような書き方をします。
というところですね。
はいはいはいはい。
受動態の方、受け身の方ではそのアクターをなるべく最後にする。
by何だらっていう風に書くことが多いですよねってことですね。
はい。
通常リーダーというのは頭の中で受動的な音声を濃度的な音声に変換するため、
処理時間がちょっと長くなりますと。
あーまあそうかもしれないですね。
リーダーというのは基本的には濃度帯の形で語られることが多いので。
対象の文章が受動態だとしても変換をする必要は確かにありますね。
まあ皆さんやられてるんだと思いますけど。
はい。
積極的な声で書く方が良いと聞いたことがある。
ならば大抵の場合はそれは理由で、そんなものは理由ですと。
テック系のライターというのはほとんどの場合濃度的な発言を好みます。
ただ、
えーっと、なんだ。
It has been suggested that… ほげほげみたいな。
どんなものが提案されていますみたいな。
そういう研究結果を引用するときは例外になりますけど。
しかしだからといって、
常に積極的な発言を求めるべきではありません。
同じ段落内であっても、
ある文から別の文に切り替えると、
効果的に使用するとコンテンツのフローというのがよりシームレスになることができますと言ってますね。
はい。
全部が全部積極的濃度的な発言とか文章にする必要ももちろんないですよと言ってますね。
はい。
続いてですね。
21:00
ミスを避ける方法みたいなところですかね。
ミスは避けましょうというところだと思いますけど。
文法とは言語の構造と正確さが全てであり、
それを実現するには文書の簡単な構成以上のものはありません。
文章からスペルミス、文法の問題、意味の不完全さというのを取り除くことが非常に重要です。
この記事の最後では、プロが書き損じを防ぐために使用する貴重なツールというのも紹介します。
明らかに最近ではほとんど全てのものにビルトインスペルチェッカーというのがあります。
まあそうですね。
はい。
ただビルトインスペルチェッカーは残念ながら英語があったりするので、
日本語のスペルチェッカーはほとんどないので基本的にはそういうのを入れるしかないですね。
VSコードの中にも一応日本語のスペルチェッカーらしかったと思うので、
プラグインして入れればいいんじゃないかなと思いますけど。
一応そういうのもありますねと。
コードエディターには間違いを防ぐためのスペルチェッカーと、
あとリントプラグインとも結構用意されてたりしますね。
しかしあらゆることに使える文法ツールを探しているのであれば、
グラマリーというのが最も広く使われているのが一つになります。
これもやっぱり英語なんですけどね。
そんなことでリビュートをもらっているわけではないですけど、
別にこれは広告でも宣伝でもないよって言ってますね。
これは多くのエディターやライターがクリーンでクリアなコンテンツを記述するために使用する非常に優れたツールです。
EMMET、ESLint、またはその他のリンターを使用してクリーンでクリアなコードを記述する方法に結構似てますよねっていうふうにおっしゃってますね。
それも確かにそうですね。
いわゆるリンター、フォーマッターとかもありますけど、
あれはコードの静的解析ツールなんですけど、
確かにクリーンでクリアなコンテンツを記述するという、
そのドキュメントの観点のツールとしても確かに捉えることができるなって思いました。
グラマリーはちなみに僕も入れてるんですけど、
きっちりきっちりいろんなツールに対応してくれるのでありがたいですね。
文法ミスとか、例えば3単元とかのエースが抜けてますよとか、
しっかり言ってくれるのですごくありがたいですね。
無料であそこまで使えるのはかなりでかいし、
優勝化したらいろいろサポートがまた増えていくので、
ちょっとお金払うか悩ましいぐらいには結構恩恵を僕は受けてますね。
では続いていきましょう。
続いてが、あと2分か。
あと2分ってことは今日この記事はさすがに読み切らんので、
これ明日続けます。
続いてはですね、Writing Code Commentsですね。
コードコメントの書き込みのところですけども。
私たちが他の開発者のために書くことは、
私たちの仕事の前提的な品質に大きな影響を与える可能性があります。
コードに何を書くか、コードをどのように説明するか、
コードに対するフィードバックをどのように与えるかなどなどです。
興味深いことに、すべてのプログラミング言語には、
コメントを書くための標準的な機能が備わっています。
彼らはコードが何をしているかを説明すべきです。
これは以下のような曖昧なコメントを意味しているわけではないですよと。
例えば、計算勝利ですね。
24:00
こういうものを掛け算して代入し直しますよとか、
もしくは代わりに詳細を示すコメントを使用しますみたいとか。
あとは赤みがかった効果を適用します。
これはCSS周りのソースコードだと思いますけど。
すべては文脈次第なんですけど、
どのようなプログラムを作成しますか、
あとは自問自答すべき質問であって、
別にコメントすべきではないよってところですね。
コメントの大事さは皆さんに語られていますし、
いろんなところでも言われていますけど、
どういうものをコメントとして書くかっていうのは、
結論的に言うと、
コードが何をしているかっていうのは、
曲のように書かなくてもよかったりします。
概要は一応あってもいいと思いますけど、
なんでこれが書かれたのか、
こういうコードになったのかっていう思想とか理由が
書かれているのが結構重要ですよね。
読めばわかるものをコメントすべきではないよと、
もちろんその通りで、
なんでっていうのを後から知らない人が
この読んだときに意図がわからないから触れないみたいなことが
よくあると思いますし、
それを避けるためになんでこれを書いたっていうその意図ですね、
理由とか思想っていうのを書くことが
コメントとしては大事なんじゃないかなと思ったりしています。
このままガーッと続いていきたいんですけど、
ちょっとすみません30分時間が来てしまったので、
今日はこちらで終了しようかなと思います。
ものすごい中途半端で大変申し訳ないですね。
明日も、もう一回多分このライティングコードコメントの
概要をもう一回重複しますけど、
読んでから入っていきたいなと思います。
明日もこのまま続けていって、
あと残っているのはライティングプロリクエストのところと、
アボイドロングPRですか、これはそうですね。
あとはリポーティングバグズ、一周の話ですね。
とかの話に入って、最後コミュニケーティングウェイズクライアントですね。
外向けのコミュニケーションとかの話を読んで終了になりますね。
ちょっと明日も長いので、
明日も読み切るかちょっと悩ましいかもしれないですけど、
今日みたいに雑談ばっかり含めなければ多分いける気がしますので、
もし興味があればご参加くださいということでした。
では今日も朝かつこちらで以上にしたいかなと思います。
今日もたくさんの方に参加いただきありがとうございました。
今日も金曜日ですね。
休み明けの金曜日だったりする方もいらっしゃると思うので、
しっかり仕事をきっちり終わらせて、
楽しい休日を過ごしていただければなと思います。
では終了します。
今日も頑張っていきましょう。お疲れ様でした。
