書評：『はじめての技術書ライティング』

期待したような本ではなかった。読む側として期待しすぎだったか。

ちょっとタイトル詐欺感は否めない。率直に言って、あまりオススメの本ではない。

概要

はじめての技術書ライティング―IT系技術書を書く前に読む本 (NextPublishing)

はじめての技術書ライティング―IT系技術書を書く前に読む本 - 向井 領治 - Google ブックス

タイトルのとおり、「ライティング」つまり書くことに重点を置いている。人文系や科学論文以外の文章の書き方の本を目指したらしい。

「はじめての」とタイトルにある割には特に工夫があるわけではなく、それなりに普段本を読んでいて、かつパソコン自体に慣れている人向け。

なお、本書はIT系の技術書や読み物を書きたい初心者に向けて、一般的な書き方を解説するものです。技術文書の書き方に関する資格試験や、企業内での製品マニュアル制作などの目的は想定していません。
向井 領治. はじめての技術書ライティング―IT系技術書を書く前に読む本 (NextPublishing) (Kindle の位置No.33-35). インプレスR&D. Kindle 版.

一般的な書き方なら他の本でいいのではと思う。

内容について

冒頭部で「技術文書の3要件」として、以下のように書いている。

（前略）技術解説の文章を書くときは、①正確であること、②論理的であること、③平易であること、の3点に注意する必要があります。
向井 領治. はじめての技術書ライティング―IT系技術書を書く前に読む本 (NextPublishing) (Kindle の位置No.173-174). インプレスR&D. Kindle 版.

おかしくはないが、技術文書の3要件はさすがに言い過ぎではないでしょうか（いきなり技術書から技術文書に飛躍しているのは大いに疑問）。

正論なので文句をつけにくいが、なんとも違和感がある。

一応、IT系固有の注意点も解説されているが、大筋としてはフォーマルな文章の書き方の範囲であまり特殊なことは書いてない。

「《筆者の場合》」というノウハウを紹介している項目は有益なので退屈な場合はそこだけ読んでもいいと思う。

電子書籍としてはちゃんと表のテキストをコピーできたり*1、かなりまともな作りでこの点は 好感が持てる。

AdobeのAcrobatを使った原稿の公正のやり取り、スクリーンショットの撮影に使うソフトウェアについてはかなり詳しく解説がある。

一般的な商業出版ならではの注意事項やヒントについては参考になる。残念ながら組版ツール側の都合からくる注意点が主体。

ただ、ごく一部の、もっと先進的なワークフローで書籍を解説している会社の事例については全然言及されていない。バージョン管理システムによる原稿の管理なんて夢のまた夢。

著者の世代の問題か、技術書を書いていると入ってもそれあくまでツールの入門書であって、「節子、それ技術書ちゃう、解説書や」という感じがする。

面白いのは「1/3」と「3分の1」のどちらがいいかという話。本の著者は後者を勧める理由として「音声読み上げツールを使う可能性がある」からという理由を提示している。年齢的な問題なのか、それとも積極的にオーディオブックなどを利用しているのか。どちらにせよ珍しい視点。

疑問に感じた箇所

データ量の単位の表記の説明で、「b」、「B」それぞれ1文字をビット、バイトという単位の表記として紹介している。間違ってはないが、普通は 「1bit」、「1byte」 とは書いても「1b」や「1B」とはめったに書かない（表やデータシートは別）。

「1b」や「1B」という表記だと鉛筆の芯、あるいは番号付きの箇条書きの見出し、図表の番号などと紛らわしい。もちろんKB、MBのように接頭辞のついた形式ではよく使う。その直後に通信速度の単位について、ビットとバイトの違いに注意しろと書いてあるだけに非常に残念。

また、KiBやMiBついても言及なし。KBやMBでは1,000倍かあるいは1,024倍かは注意すべきポイントのはず。表記について注意喚起するならそこは徹底してほしい。

もう一点、難読漢字をどうするか、ルビを表記することに対してこの本の著者は否定的。これは納得しかねる。活字を並べていた時代はコスト的に厳しかったかも知れないが、紙と電子版で見せ方を変えることもできるのだからルビは積極的に使うべき。技術的な観点から言えば少なくともHTML5には<rub>タグがある。

紙媒体と電子書籍について

注釈についての注意書きの箇所。注釈に関する文章なんだけど電子書籍に関する見解について。

（前略）そもそも脚注はできるかぎり使わず、本文の中で記述することをおすすめします。脚注は本文とは別の場所へジャンプする必要があるため読みづらくなりますし、電子書籍ではページの移動が印刷書籍よりも面倒だからです。
向井 領治. はじめての技術書ライティング―IT系技術書を書く前に読む本 (NextPublishing) (Kindle の位置No.1499-1501). インプレスR&D. Kindle 版.

これは疑問。電子書籍リーダーの問題をメディアの問題と混同している。あるいは電子書籍リーダーの機能を知らないか。

注釈のリンクをクリックしたあと前のページに戻れるし、KindleのPage Flip機能や検索などページの移動については紙より便利。
どうも認識が古いんではないか。

悪文云々について（5.3節）

5.3節に代表的な悪文について解説がある。そもそも技術書に限った話ではないし、今ひとつ説得力に欠ける。

なんとなく世間体の観点から説教している感じの解説。

• 「技術所では習慣的にひらく漢字：技術書でなくても「かな」表記だと思うけど？
• 難読漢字：よく使う単語、熟語は漢字表記にするかルビ付きにすればいい
• 名刺止め、体言止めを悪文呼ばわりはちょっと言い過ぎ

「つたない印象を受けるから云々」という説明は説得力にかける（この本、「つたいない印象」が1回、「大変つたない印象」が2回）。

この書籍の悪文についての解説を読むよりも、数学文章作法シリーズのほうがいい文章がかけると思う。

紹介されているツール

マインドマップに関するものを除けば特に珍しくはない。Scrivenerについては著者の前著を参照とかいてあるぐらいで特に解説なし。

• アイディア出し
  • iThoughtsX/IThoughts マインドマップ作成（有償）
• 執筆
  • Scrivener
• 仮想環境ツール
  • VirtualBox
  • VMware Workstation
  • Parallels Desktop
• スクリーンショット
  • Snipping Tool
  • Quitcktime（iOS系）
• PDF関連
  • PDF Expert
  • Acrobat
  • Acrobat Reader
• その他
  • ATOK
  • 共同通信社 記者ハンドブック for ATOK

感想

本の著者の年齢が1969年なので考え方が古い印象を受けた。ライティングというタイトルの通りの内容ではあるが、技術書というタイトルにマッチした内容かといわれると微妙な気がした。

文章に変に癖がなく読みやすいの確かで、そのあたりは流石は商業ライターといったところ。

技術文書ではないので別にいいのかもしれないが、パソコン雑誌の文章の書き方指南書というのが一番しっくりくる本。

技術者として働いているならそれなりに文章を書く訓練は受けているだろうし、この本の内容はあまり役に立たないと思う。もちろん再入門としてなら別。
ライティングそのものという観点ではほかにもいくらでも良書がある。

まとめ

上にも書いたがKindle版のつくりが非常にいい。内容はちょっと不満はあるが大筋としては悪い本ではない。少なくとも内容が気になって買うかどうか迷うよりは （半額で買えたので）買ってよかったかなと思う。

他の文章の書き方の本を読んで物足りないならともかく、まずは他の本を読むことをおすすめしたい。

特に同人系のイベントで技術書を書きたいなら、タイトルに技術同人誌と明記している以下の本がいい。

技術同人誌を書こう！　アウトプットのススメ (技術書典シリーズ（NextPublishing）)

一般的な商業出版についての原稿を各側の予備知識を得る本としては及第点か。 中途半端な感じは否めず。

数学文章作法 基礎編 (ちくま学芸文庫)

数学文章作法 推敲編 (ちくま学芸文庫)

*1:表の部分が画像ではないという意味

厚生労働省ブラック企業リスト6月版（2018年）

今月も恒例の公表事案。

a244.hateblo.jp

今月も月末更新。

データの入手元

www.mhlw.go.jp

ファイルは労働基準関係法令違反に係る公表事案というリンクから。ただし、毎月同じファイル名で更新される点に注意。

いつもどおりですが、今月は労働局によってはデータが更新されていないっぽいです。最終更新日が3月古いのままの労働局（都道府県）*1がいくつかあります。

機械可読データ（タブ区切りテキスト形式）

厚生労働省ブラック企業リスト（2018年06月29日版） 　

PDFからTSVへの変換スクリプト

Convert PDF to TSV ( for Japan's MHLW illegal company list ) rev. 2

先月と同じで変更なし。

退屈なことはPythonにやらせよう ―ノンプログラマーにもできる自動化処理プログラミング

前月との比較

先月の458件から440件に減少（差分は18件）。

トータルで公表件数が増えているのは新潟労働局、静岡労働局、滋賀労働局、山口労働局、沖縄労働局の5労働局。

トータルでプラマイゼロですが、青森労働局、大阪労働局、広島労働局は新規掲載が2件以上。愛知は新規追加件数より掲載終了が多いのでトータルではマイナスですかここも2件以上。

全体的に掲載終了の事業所が多い。また、3月から掲載内容に変化がない労働局もいくつか。特に目立った企業名は無い。

労働局名	当月公表件数	前月公表件数	新規掲載	掲載終了	差分
北海道労働局	22	23	0	1	-1
青森労働局	8	8	2	2	±0
岩手労働局	9	11	0	2	-2
宮城労働局	4	5	0	1	-1
秋田労働局	4	4	0	0	±0
山形労働局	4	4	0	0	±0
福島労働局	10	10	0	0	±0
茨城労働局	4	4	0	0	±0
栃木労働局	8	8	0	0	±0
群馬労働局	5	5	0	0	±0
埼玉労働局	9	10	1	2	-1
千葉労働局	8	10	0	1	-2
東京労働局	19	22	1	4	-3
神奈川労働局	9	9	0	0	±0
新潟労働局	12	11	3	2	+1
富山労働局	4	5	0	1	-1
石川労働局	6	6	0	0	±0
福井労働局	8	8	0	0	±0
山梨労働局	10	12	0	2	-2
長野労働局	19	19	1	1	±0
岐阜労働局	11	12	0	1	-1
静岡労働局	9	8	1	0	+1
愛知労働局	30	31	2	3	-1
三重労働局	10	11	0	1	-1
滋賀労働局	8	7	1	0	+1
京都労働局	7	8	0	1	-1
大阪労働局	28	28	2	2	±0
兵庫労働局	15	17	0	2	-2
奈良労働局	4	5	0	1	-1
和歌山労働局	9	9	0	0	±0
鳥取労働局	2	2	0	0	±0
島根労働局	7	7	0	0	±0
岡山労働局	7	7	1	1	±0
広島労働局	17	17	3	3	±0
山口労働局	5	4	1	0	+1
徳島労働局	5	5	0	0	±0
香川労働局	0	0	0	0	±0
愛媛労働局	12	12	0	0	±0
高知労働局	7	7	1	1	±0
福岡労働局	15	15	1	1	±0
佐賀労働局	5	6	0	1	-1
長崎労働局	4	4	0	0	±0
熊本労働局	11	12	0	1	-1
大分労働局	11	11	1	1	±0
宮崎労働局	1	2	0	1	-1
鹿児島労働局	7	7	0	0	±0
沖縄労働局	11	10	1	0	+1

まとめ

氷山の一角であるはずなんですが、この件数。労働基準監督署のリソースの問題ですかね。

掲載件数が少ないからといってその労働局の管轄エリアがホワイトとも言えませんし。管轄エリア別の事業所の分布、業界など、いろいろ考慮するともう少し いろいろと分かるのかも知れません。

今月も手抜きですがここまで。

エキスパートPythonプログラミング改訂2版

労基署は見ている。 (日経プレミアシリーズ)

労基署がやってきた! (宝島社新書)

*1:鳥取労働局が1月のまま

macOSとスクリーンショット

備忘録というかメモ。

基本

基本的なやり方

• 画面全体： Command+Shift+3
• 画面の選択範囲： Command+Shift+4、カーソルの形が変化したらドラッグ
• ウィンドウ単体： Command+Shift+4、Spaceキーを押してからウィンドウをクリック
• Touch Bar： Command+Shift+6

撮影されたスクリーンショットはデスクトップに保存される（El Capitan以降）。

ウィンドウ単体のスクリーンショットを撮る際、escキーでキャンセルできる。

海外のサイトによると、次期macOS Mojaveでは新しいスクリーンショット用のツールが追加されるとのこと（Command+Shift+5）。

標準搭載のグラブ.app（Grap.app）というアプリケーション、QuickTimeを使う方法もある。

クリップボードにダイレクトにコピーしたいとき

スクリーンショットの撮影時にcontrlを同時に押すとクリップボードに画像データが保存される。

• 画面全体： Command+Shift+3+control
• ウィンドウ単体： Command+Shift+4+control

他のキーを指で抑えた状態で最後に数字キーを押すとラクに操作できる。

ダイレクトに画像編集ソフトにペーストできて便利。

ウィンドウの影を消す

ウィンドウ単位でスクリーンショットを撮ると、ウィンドウの影のついた画像が保存される。

クリック時にoptionキーを押せば影のない画像が保存される。

マウスカーソルつきのスクリーンショット

グラブというアプリケーションを使えば可能。

1. グラブを起動（面倒ならCommand+Space、grab.appと入力）
2. Commad+,で設定画面を開く
3. スクリーンショットに入れたいカーソルの形状を選ぶ

スクリーンショットに関する設定

基本的にTerminal.appなど、コマンドを実行することで設定を変更。

SystemUIServerというバックグラウンドで実行されているプロセスの再起動が必要なケースと、そうでないケースがある。

保存先の変更方法

初期設定ではデスクトップに保存されるので少々不便です。

$ defaults write com.apple.screencapture location <path>
$ killall SystemUIServer

defaultsコマンドで設定をを書き込み、killallコマンドでSystemUIServerプロセスを再起動。

設定したい保存先に合わせてを変更。

Web上の情報では基本的にはピクチャフォルダ（Picture）に保存する人が多い印象。

設定例：

$ defaults write  com.apple.screencapture location ${HOME}/Pictures/

念の為、SystemUIServerを再起動。

$ killall SystemUIServer

※ 環境変数${HOME}がユーザーのホームディレクトリに展開される。

現在の設定はターミナルで以下のようにdefaultsコマンドにreadオプションを指定して実行すると確認可能。

$ defaults read com.apple.screencapture location

保存形式の変更

保存形式を標準のPNGから変更可能。

$ defaults write com.apple.screencapture type jpg

typeの値として保存形式を指定する。他の形式としては bmp、pdf、tiffなど。

試した限りでは設定の変更は即座に反映された。

ファイル名の接頭辞（文字列）の変更

ファイル名のパターンを完全に独自形式にすることはできない。部分的には変更できる。

$ defaults write com.apple.screencapture name 文字列

文字列の部分を自分で設定したいファイル名の接頭辞に変更。

元に戻したい場合は設定値を削除。

$ defaults delete com.apple.screencapture name

ファイル名に日付と時刻を含むかどうか

$ defaults write com.apple.screencapture include-date -bool false

この状態で連続でスクリーンショットを撮ると、ファイル名が「スクリーンショット.jpg」、「スクリーンショット 1.jpg」、 「スクリーンショット 2.jpg」という形式になる。連番の数字の前にスペースが入っているので注意。

元に戻したい場合は設定値の削除（または-bool trueとして上記コマンドを実行）。

$ defaults delete  com.apple.screencapture  include-date

デフォルトを影なしにする設定

いちいち影なし・影ありをoptionキー切り替える必要がない場合は、設定で常時影なしにできる。

$ defaults write com.apple.screencapture disable-shadow -bool true

もとに戻す場合は値をfalseにするか、パラメータ自体を削除する。

$ defaults write com.apple.screencapture disable-shadow -bool false
$ killall SystemUIServer

または、

$ defaults delete  com.apple.screencapture disable-shadow
$ killall SystemUIServer

まとめ

mac関連の雑誌でもoptionキー同時押しで影なしのスクリーンショットが撮れるというTipsは紹介されていなかったと思う。

元ネタは海外のサイトからというケースが多いけど、海外のサイトはどうやってマニュアルにも公式サイトにもない情報を得ているのか不思議。 Apple社員がリークしている？

参考リンク

• macOS Sierra: 画面を撮影する
• OS X Lion: 画面を撮影するためのショートカット
• How to Control the Behavior of Screenshot Shortcuts in macOS - Mac Rumors
• Macでスクリーンショットを撮る方法と保存先＆形式を変える方法 - Qiita
• macOSの一歩進んだ画面キャプチャテクニック - Qiita

macOS High Sierra パーフェクトマニュアル

[基礎知識+リファレンス]macOSコマンド入門 ――ターミナルとコマンドライン、基本の力

今週のふりかえり（2018年6月第4週）

雨は売っと惜しいけど、晴れの日に風が吹くといい感じ。

あと一週間で６月もおしまい‥…。

「機械学習で男性エンジニアを女性に」という炎上案件について

いまいちコンテキストが理解できないのだけど。

logmi.jp

その場に「いなかった人」がどうも文脈を把握しきれずに騒いでいる感じがする。

これ音声を機械学習で変換しようという技術についての発表ですよね？

女性エンジニアが少ないことと、機械学習は何の関係も無いのに女装写真とか変な前振りをつけているっていう。

悪気はなかったんではないかな。

研究の動機の話

男性の声を女性の声に変換するメリットについて、説得力のある説明ができなかったのではないかと思う。

なにか発表しろと言われて、音声の変換というネタはあるんだけど、イントロダクション部分がイマイチだった。 そこでだれかの入れ知恵か、無理にこじつけで「女性エンジニアが少ない」という話題にこじつけたか、笑いを取りに行ったのか。

学会発表向けのスライドだったら前後のロジックに無理がありすぎて普通にストップがかかるはず。

所属がYahooの中の人らしいのでだれか社内で止める人がいなくても不思議ではないのかも。

前フリと発表の対象技術がちぐはぐなのは確か。

アプローチがまずかっただけでは？

コナンくんの蝶ネクタイ型変声機ネタで攻めればよかったのはでは？

名探偵コナン　メガジャンボ寝そべりぬいぐるみ　江戸川コナン　夏服Ver.

女性エンジニアがいないと云々という言い回しが一種のセクハラ加害者的な発想と受け取ららたのかなという理解。

男性が女性の前で格好をつけたがるというのは割とよくある話で、とある企業のリストラの際に、あえて女性秘書を同席させたという話もある*1。

「クビ!」論。

確かに女性側からしたら不快なんだろうけど、本人は深い考えはなしに、男子校のノリで笑いを取りに行ったんだろうと思う。

技術的にどこまでのレベルか知らないけど、その場のウケを狙うなら、コナンくんネタで行けば良かったのにと思う。

軽度難聴の観点から

聴力低下の副作用で相手の声質によって極端に聞き取りにくい時がある。聴力低下によるダイナミックレンジの低下が原因なんだろうけど、 この声の変換技術、補聴器に組み込むとかそういう応用が期待できるという気がした。

むしろそういう笑いを取るネタではなく、真面目に実用路線でアピールして欲しかった。

お役人様から予算を引っ張るのに有効だよきっと。

職業名に「女性」という修飾語をつけることに関して

特定の職業において、性別に偏りがある、というのは多様性の問題。そもそも、エンジニアって性別に影響されない職業だと思っていたのですが、違うんですかね？

「女性〇〇」という表記がおかしいんではないでしょうか。

まずマスメディアが好んで使うそういう、「女性〇〇」っていう表記、それ自体が暗黙に普通は女性はこの職業には就かない、という偏見を助長していると思います。

男性看護師といえば違和感に気づくはずです。女性社長とか女性起業家とか、そうやって都合のいいときだけ「女性」を強調するし。

日本は言霊の国()らしいのでそこからちゃんとしないと。

まとめ

不適切な表現があったからと言って、技術の可能性をと切り捨てないでいただきたい。声質変換でググると結構ヒットするので技術的には 実績のあるテーマみたいだし。

音声系の技術は耳の悪い人間のQoLの向上とか、笑いを取る以外の応用を目指してほしい。健常者にはありがたみがわからないんだろうけどね。

やっぱりその場にいなかった人が大騒ぎして、拡散させているのは違和感ある。

音声認識 (機械学習プロフェッショナルシリーズ)

*1:男性は女性の前でみっともなく泣きわめきづらいという解説が書いてあった