Docs Like Code を買った

技術文書に関する本をまた一冊購入しました。

https://amazon.jp/dp/1387081322/amazon.jp

内容を一言で紹介するならば、「技術文書を書くときもソフトウェアを書くときと同様に Git と GitHub を使いましょう」というものです。

Docs Like Code の考え方は次の記事にわかりやすく書かれています。Docs-from-Code というのも参考になりました。

sysdig.jp

実は、私は 2 年ぐらい前に Git や textlint を使ってドキュメント管理し CI の中で構文チェックを行うようなしくみを構築したことがあったのでいろいろ思うとこことがありました。

ソフトウェア開発者寄りの見方ではソフトウェア開発と同様のワークフローを採用することで開発者を巻き込みやすくなるというメリットを感じました。 実際に、何度か開発者から直接プルリクをもらうこともあり、実際にそのメリットを実感できました。

一方で、ライティングの中心となるライターさんが Git を使いこなせずに結局使われなくなるという苦い思いもしました。 今思えば Docs Like Code によって得られるメリットがライターさんの立場では小さかったため、自ら Git を学習しようというようにならなかったのだと思います。

今思えばライターさんたちの関心はワークフローの改善ではなくより上流の問題にあったため Docs Like Code によって得られるメリットが小さかったのではなかいと思います。 自分自身が得られる恩恵が少なければ、自ら Git を学習しようというようになりませんよね。

このことから、ソフトウェア開発者が中心となるプロダクトでは Docs Like Code の考え方を浸透させる余地はあるのでしょうが、一般向けのプロダクト開発においてはこれだけでは受け入れにくいだろうなと思います。

(なんだか愚痴みたいになってしまいました。)

Living Documentation 買った

タイトルの通り『Living Documentation: Continuous Knowledge Sharing by Design』を買っかという話です。

www.amazon.co.jp

この本を知ったきっかけは、Learning Domain-Driven Designで紹介されていて、そのタイトルに惹かたために購入しました。

www.amazon.co.jp

内容をひとことで表現すると、文書作成についてのデザインパターン本です。デザインパターンというのはシステム開発ではお馴染ですね。

すでに Learning Domain-Driven Design で紹介されていたと説明しましたが、DDDの戦略的設計に関する部分を補完する内容のように捉えました。

DDDに関して言えば、戦略的DDD(何を実現するか)よりも戦術的DDD(どのように実現するか)が強調される場面が多いように感じます。 これは、ビジネスにおいて、初期はスピード重視であること、軌道に乗ってからは負債の解消に負われてしまうことなどから、「何を実現するか」というようなドメインについての理解を深める余裕を十分に生み出せません。 ただ、(矛盾したようにも感じますが)ビジネスが成長し多様な人間が関わるようになると、関係者の間で共有すべき事項すなわち戦略的な側面が大切です。

そのようなことを考えながら偶然出会ったのが本書でした。ざっと満た感じでは平易な文章でそれほど英語が得意でなくても読み易いと感じました。

ひとまず今日は内容には触れません。おやすみなさい。

読書時間がとれない人のための音声入力〜音声入力を活用した効率のよい読書メモのススメ〜

macOS の音声入力機能が思いのほか便利だったのでブログにまとめてみます。

自分について

自分の属性を簡単にまとめると次の通りです。

  • Web アプリケーションエンジニア
  • 読書は好きだが、仕事関係の本を読む時間はない
  • 子ども（2 歳）がいる

読書に対するモチベーションとしては、読書を通じた学習はしないといけない、積極的にしたいという気持ちはありますが、今は平日・休日ともに子どもとの時間を優先しています。読書会に参加もしていません。

また、読書のための時間を数時間まとめてとることは基本的に難しく、1 日に数十分〜 1 時間未満の時間を数回に分けて捻出しています。

書籍との付き合い方

書籍は月に数冊は購入します。セールのときは Amazon Kindle や PDF で買うこともありますが、それ以外は紙の本を買います。

正直、紙・電子のどちらにもメリットは感じていますが、内容が高度になるにつれて紙の書籍を複数同時に開いて比較しながら読む方が理解しやすいと感じています。

かさばる本は紙・電子の両方で買っていることが多いです。 これは、2 冊同時に買うのではなく、版が新しくなったときや翻訳が出版されたときなどに別のフォーマットで買いなおしているためです。 あえて両方買うということはないです。

本を読むときは、基本的には自宅で椅子にかけて読むことが多いですが、出先で時間ができたときは iOS で電子書籍をよく読みます。

読書メモの効率を上げる

読書メモはあまり取りません。 ただ、洋書（特に技術書）では、センテンスごとに理解した内容を翻訳してメモをとることが多いです。 これは、あまり英語力に自信がなく、あとで読んでいた内容をわからなくことがよくあるので、あとで参照しやするなるようまとめるようにしています。

日本語の書籍の場合は、書籍に対してメモをとることはありませんが、特定のトピック（たとえば、関数型プログラミング・デザインパターンなど）ごとに書籍からの引用を抜き書きしてまとめるようなことはあります。

音声入力が便利と感じるようになったのは前者のような場合です（後者の抜き書きのような場合だと、正直、コピペしてしまった方が楽です）。というのは、翻訳する場合は次のようなプロセスを経る必要あり、手数が増えてしまうためです。

  1. 英文を読む
  2. 頭の中で日本語におきかえる
  3. キーボードを打つ
  4. 文章を推敲する・整える

音声入力にすることで 1、2 に集中できます。 音声なのでキーボード入力がなくなるのは当然ですが、翻訳でつまったときも修正内容をそのまま書いておいてあとでまとめて整えることができます。

むしろ、英文を読むときは粗くともすばやく流れを意識した方が全体として理解しやすくなります。細かな部分の理解を推敲するときに修正してゆく方がより効率よいと感じます。

音声入力を有効化する方法

maoOS の音声入力はデフォルトでオフになっているのでシステム設定 > キーボードから設定を有効にする必要があります。以下に Apple のドキュメントから設定方法を引用します。

  1. Macで、アップルメニュー ＞「システム環境設定」と選択して「キーボード」 をクリックし、「音声入力」をクリックします。
  2. 「オン」をクリックします。確認を求めるメッセージが表示されたら、「音声入力を有効にする」をクリックします。

音声入力を有効にする設定画面のキャプチャー

support.apple.com

音声入力を利用するメリット

メリットについてはすでに少し述べました。

最も大きなメリットは、「メモをとる」という作業から解放されて「本を読む」作業に集中できることです。

このほかにもいくつかメリットをあげるとすれば、iOS、iPadOS の音声入力を使うことでソフトウェアキーボード入力のストレスが軽減されることかなと思っています。

これは、PC のキーボードに比べてソフトウェアキーボードが使いづらいということでもあります。 加えて、紙の本を開いてさらに iOS のメモアプリを開き、それぞれを持ち替えてメモをとるのは現実的でありません。

電子書籍からメモをとることは今のところありませんので想像ですが、iPad で電子書籍とノートアプリを同時に起動しソフトウェアキーボードで入力するときに画面いっぱいなってしまいます。 画面にさまざまなものが表示された状態で作業すると、混乱してうまく作業できなくなってしまいそうです。

いずれのケースも、移動中の明き時間に「ちょっとメモしておきたい」というような場合であれば音声入力で記録しておいて、まとまって時間ができたときに推敲することで十分なように感じています。

音声入力を利用するデメリット

実際に感じたデメリットとしては、夜に音声入力を使っていたら子どもを起きてきてしまったことがありました。小声でもたいてい聞きとってくれるのですが、注意が必要です。

はまったポイント

「改行」と言えば改行してくれる便利機能があるのですが、即時に反映されず音声入力を終了した時点でまとめて反映されるというような仕様（？）になっていたことでした。

まとめ

周りの音を拾うこともほとんどなく快適に利用できています（ただ、家族に近くで話しかけられるようなときに文章が乱れてしまうようなことはありました）。

空き時間を活用して読書するような場合には、音声入力は非常に役立つソリューションだと感じています。

ちなみにこのブログも子どもを昼寝させている時間に音声入力で下書きして、夜寝かしつけてからまとめました。

Technical Writing One introductionがよかったので読書メモを書きました

まとまった文章を書く機会が増えたので、Googleの公開しているTechnical Writing One introduction（以下、One introduction）を読みました。この記事はその読書メモをまとめたものです。

developers.google.com

Googleが公開する学生向け（For Student)のコンテンツは、Technical Writing Two introduction（以下、Two introduction）もあります。 Two introductionは発展的・ソフトウェアエンジニアリングにより特化した内容ですので、より汎用的なOne introductionの内容を読みました。

なお、これらのコンテンツはすべて英語で書かれていますので、当然英語の文章を前提とした説明になってます。しかし、大半は日本語の文章に応用できる内容でした。

この記事を書くにあたって、次の日本語の要約記事をたいへん参考にさせていただきました。

qiita.com

qiita.com

また、直接的な関係はありませんが、Amazonの文書構成術の記事にも共通するものがありました。

note.com

目次

One introductionは次のページにより構成されています（強調は筆者）。

  • Introduction (3 min)
  • Just enough grammar (optional) (10 min)
  • Words (10 min)
  • Active voice (15 min)
  • Clear sentences (10 min)
  • Short sentences (20 min)
  • Lists and tables (15 min)
  • Paragraphs (10 min)
  • Audience (10 min)
  • Documents (10 min)
  • Punctuation (optional) (5 min)
  • Markdown (variable)
  • Summary (1 min)

この記事では太字にしているページから、要点を箇条書きで取り上げます。

Word

  • 新しい用語を定義する
  • 用語を統一する
  • 頭字語を使う
    • 頭字語は、文章の中で最初に使うとき省略しない表記で書く
    • 省略しない語（頭字語）を太字にする
      • 例）Telekinetic Tactile Network（TTN）
    • 短かすぎる頭字語は、読者が解釈するのに時間がかかるので注意する

Active Voice

  • 能動態と受動態を区別する
    • 受動態は主語（誰が）を省略できる
    • よい技術文書がは、「誰が」・「何を」・「誰（何）に」が明確である
  • 能動態を使用した方が良い
    • 読者は受動態を能動態に変換して解釈するので、手間がかかる

Clear sentences

  • 強い動詞を使う
    • 強い動詞=他動詞、弱い動詞=自動詞ということ？
  • 特定の形容詞は使わない
    • とても速い → 225-250%速い

Short sentences

  • ひとつのアイデアに各文を集中する
  • 長い文はリストに分割する
  • 冗長な言いまわしをしない

Lists and tables

  • リストには3種類ある
    • 順序なしリスト（bulleted lists）
      • 並び替えて意味がかわらない
    • 順序ありリスト（numbered lists）
      • 並び替えて意味がかわる
    • 埋め込みリスト（embedded lists）
      • 手順のようなもの？順序なしリスト、順序ありリストに変換するとよい？

Paragraphs

  • パラグラフの書き出しが重要
    • 忙しい読者は読み飛ばすため、書き出しに中心となる話題を書く
  • ひとつのトピック（主題？)に各パラグラフを集中する
  • 読者が歓迎するパラグラフの流さは3-5文ほど
  • パラグラフは次の3つ要素で構成するとよい
    • 何を読者に伝えたいか？
    • それを知ることが読者にとってなぜ重要なのか？
    • 読者はその知識をどのように使うべきか？

Audience

  • 良いドキュメント = 読者が知る必要のある知識・スキル - 読者が知っている知識・スキル
    • 読者がすでに知っていることを説明しない
    • 熟練者が書き手である場合は、初心者が知らないことを簡単に忘れるので注意が必要

Documents

  • 良いドキュメントには対象読者・スコープが書かれている
    • より良いドキュメントには説明しないことが書いてある
  • プロの書き手は、読者が2ページを開く確立をあげるために、1ページ目に考慮可能なだけの労力をかける
  • 主題をそれを構成するセンテンスに分け、細分化して文章を書く

まとめ

基本的には文章を書く上で知っていた方がよいことを簡潔にまとめられていました（Clear sentencesのページはあまり意識してないことが多かったです）。

読書メモを書くときに、意訳してしまった点や、十分に考察しないまま書き連ねた箇所がありました。 文意を正しく知りたいという方は原文を読んでください。

コマンドラインから画像ファイルを base64 エンコードし、HTMLに埋め込む

Google Spreadsheet の html に画像を表示するとき、base64 にエンコードすることで表示できた。

コマンド

カレントディレクトリにある img.jpg というファイルをエンコードする。

$ base64 img.jpg

この出力を img タグの [output] の部分に書く。

JPEG

PNG

GIF

SVG

参考

blanche-toile.com

パフォーマンスがいけてない not exists 相関サブクエリを left join で書き替える 

select 
  *
from
  table1 t1
where
  not exists (
    select 1 
    from table2 t2 
    where  
      t1.id = t2.id -- <- ここ
);

例の如く、適当な SQL だが、サブクエリで外部の値を使用している。これを left join で書き替える。

select 
  *
from
  table1 t1
  left join table2 t2
    on t1.id = t2.id
    and t2.id is null;

参考

qiita.com

MySQL の DEPENDENT SUBQUERY について

MySQL のサブクエリは重い。という記述をしばしば目にするが、実際に遅い場合があるのは「DEPENDENT SUBQUERY」である。

DEPENDENT SUBQUERY とは

いわゆる、相関サブクエリというやつである。サブクエリ内で外部のテーブルと結合するようなときがこれに該当する。

SELECT
  *
FROM
  table1 t1
WHERE
  t1.id in (SELECT id FROM table2 t2 WHERE t2.id = t1.id); -- サブクエリ内で t1.id を使用している

雰囲気こんな感じ。

代替策

JOIN を使う。

SELECT
  *
FROM
  table1 t1
  INNER JOIN table2 t2 ON t1.id = t2.id;

参考文献

nippondanji.blogspot.com

www.amazon.co.jp

fulfillment-c.com