テクニカルライティングのポイント

参考元

Google社のテクニカルライティングの基礎教育資料がとても良かったので紹介したい - Qiita

ポイント

  • 用語は文書内で一貫性をもたせる
  • 曖昧な代名詞の利用は避ける
  • 受動態は避け、能動態を優先する
  • 強い動詞を選択する1
  • 曖昧な動詞よりも意味が限定される動詞を選ぶ
  • 1文1メッセージ
  • 長い文章はリスト形式に変換する
  • 不要な言葉は排除する
  • 順序が重要な場合は番号付きリストを使用し、順序が重要でない場合は箇条書きリストを使用する
  • リストを使う場合は言葉の並列性を保つ
  • 番号の付いたリストは命令語で始める
  • リストと表を適切に使う
  • 段落の骨子を示す良いリード文を作る
  • 1段落1トピックに絞る
  • 読み手に伝えるべきことを定義する
  • 読み手を意識して書く
  • ドキュメントの最初にそのドキュメントの重要なポイントを明確に示す

コーチング

一般的にはゴールなどを本人から引き出すことが多いが、個人と組織を踏まえた場合にそのゴールが足りていなくてもそこまで踏み込んで話さないことが多い。 そういう場合には、潜在的なwillをコンサル的に引き出すと良い。

As Is, To Beを引き出すために * 傾聴(聞く):関係を構築するために行う。一方的に答えを提示しない * 承認(褒める):結果だけではなくプロセスも承認する。変化しようとすることを承認する * 質問

ソースコメントも理路整然に

ソースコメントにはWhy notを書くのが良いと言われている。 (ソース意図について5W1Hに関する情報はコミットログから読み取れるため)

そんなソースコメントについて、口語体で開発者の実装当時の気持ちが見え隠れするようなコメントを見かけることがある。

...きっと実装が大変だったのだろう。

でもそんな時こそもう一息入れて最後までやりきろう。

ソースは一行一行、一言一句、こだわりぬいて書くものである。それはコメントもしかり。

ソースをロジカルに考えて書く力があるのだから、コメントも理路整然と書こう。

将来の読み手の負荷低減に繋がる。

このソースを書いた人は果たしてロジカルに考えられる人なのか?という疑心は、

自動車の運転が荒い地域をいつもより気張ってかもしれない運転するように徐々に身体の疲労に響いてくるのだ。

チームシップとして期待すること

チームシップとして期待すること

  • さまざまなことに興味を持ち着実に解像度を上げていくこと
  • ひとつ上の立場の人たちであれば行うであろうフレームに対する貢献について考えること
  • ひとつ上の立場が人たちであれば行うであろうラストマンシップについて考えること
  • もし未踏案件で想像より時間がかかったとしても現在や未来へ還元していくこと
  • 個としてのキャリア形成をしていくこと

 ※フレーム: 組織など

キャリアロールモデル

特定の人物を思い浮かべられる人はその人の考え方や行動を自身に取り入れていく。 スポーツでプロを目指す人がトッププロの練習方法を真似してみるのと同じこと。 それはエンジニアも同じ。

特定の人物が思い浮かべられない人は、何かの拍子にこの人すごいなーと思ったときにそこで終わるのではなく、 その人に近づけるように1つずつ行動を変えていく。

開発環境のパッケージング

ローカル環境を汚さずDockerコンテナのオーバーヘッドもなく、開発環境を自在に構築できる「Devbox 0.2.0」登場

https://www.publickey1.jp/blog/22/dockerdevbox_020.html

Devbox

  • Jetpack Technologies社がオープンソースで開発しているのが「Devbox」(マイクロソフトによる仮想化された開発環境の「Dev box」とは別のもの)
  • ローカル環境上に分離した環境を用意しそこで開発環境を構築可能にしつつ、Dockerコンテナのような仮想化技術を用いていないことが最大の特徴
  • Devboxの基盤はLinuxディストリビューション「NixOS」のパッケージマネジメントツール「Nix」

開発環境系の製品

  • マイクロソフト: Dev Box
  • Google Cloud: Cloud Workstations
  • AWS: Amazon CodeCatalyst

  • Daggerも、CI/CDパイプラインをポータブルにする取り組みとして注目されている

State of JavaScript 2022

JavaScript開発者の利用傾向や人気ツールは?--「State of JavaScript」調査

https://japan.zdnet.com/article/35198679/

フロントエンドフレームワーク

  1. React 82%
  2. Angular 49%
  3. Vue.js 46%
  4. Svelte 21%

レンダリングフレームワーク

  1. Next.js 49%
  2. Gatsby 23%
  3. Nuxt 18%

所感

Svelteの勢いは落ちつきあると言う雰囲気を感じていたが、依然と関心は集まっているもよう