『技術者のためのテクニカルライティング入門講座』を読んだ

読んだので感想とともに紹介をば。

対象

タイトルの通りテクニカルなドキュメントをこれから書き始めなきゃいけない人向け。主に業務になって初めて、日本語のドキュメントをたくさん書かなくてはいけなくなったけれど、何から始めればよいのかよく分からない人向け。

文字も大きく、全体的な体裁が比較的ポップめなので個人的にはあんまり好みじゃないんだけど、内容と対象とはマッチしていると思う。

総評

  • ライティングについて「初歩的な部分」からコンパクトに紹介されていてよい
  • 前半は基本、後半は実例で、実例はユーザーマニュアル、提案書、障害報告書、社外メール文というのも扱いやすい

ライティングというと鉄板ネタとして「作文技術」「文章作法」系があるんだけど、もっと実用に寄っていてかつある程度汎用的なワークフローの中に落とし込めるかという意味では、物足りなかったり、不必要に詳細だったりして、紹介しやすい本があまりないなーと感じていた。

簡単に言うと普通の人は論文や本のようにボリュームのあるものを「読んでもらえる」機会はほとんどない。コンパクトでかつ大切なことが必要十分に伝わるように書くことを求められる。また業務の場合、提出先があり、多くの場合は事前にレビューがある。

これまで自分は主に『ドキュメントハックス』を紹介するようにしていたんだけど、さすがに古くなってきていたのと、こちらの方が横書きで図表も豊富なので、まさに「今」に即しているように見える。今後はこれをまずテキストとして紹介していこうと思う。

使えそうな部分

  • まずは 1 から 3 章がやはり基本
  • 4章はやや伝統的なビジネス文書のルールに近い。押さえておくと「何か」とやりやすくなる
  • 5章以降は実践編1
  • ドキュメントレビュー時に使う『リーダブルコード』のような位置付けで使うとよさそう

  1. 障害報告とか、原因も特定してねーし対策にもなってねーぞ、みたいな報告見ると萎え萎えなのでみんな気をつけてね ↩

Vue.js x SSRメモ

これ読め。

Introduction · GitBook

Nuxt をちょっと使った程度で気になったところだけを抜粋。

まず prerender を検討せよ

SSR は考えることが増えるので prerender をお勧めされる。

vue-server-renderer

vue-server-renderer が String を生成してくれる。

express などサーバサイドのフレームワーク上で Vue component を利用してページ生成することができる。

VM Life Cycle が異なる

Server Side では data reactivity は不要であり、VM life cycle は以下の 2つしかない。

  • beforeCreate
  • created

だから created() で store の registerModule を route に応じて行う Nuxtでrouteに応じてVuex Storeをmodule分割する方法 - あーありがち(2018-04-19) コードを試した時に訳の分からない動きをしたのか。

custom directive は要注意

  • 多くは生DOMに依存するので動かない
  • <no-ssr> で回避できる

Nuxt や egoist/vue-no-ssr: Vue component to wrap non SSR friendly components (428 bytes) で利用できる。

自分で実装する際には custom directive ではなく component にして VirtualDOM にする方法を選択すべし。

stateful な singleton を排除

サーバサイドの Node.js プロセスは長寿命であり、Vue のレベルで singleton を作ってしまうと複数のリクエストで状態が share されてしまう。

routing を vue-router に

サーバサイドフレームワークの routing を素通しにして vue-router で routing を行うことで client-side と同じ動きにできる。

サーバサイドでの dynamic component の lazy loading は危険

const Page = () => import('Page.vue')

みたいなやつ。

以前試したのだが、2つ問題があった。

一つはサーバサイドで実現するには描画開始前に非同期コンポーネントを先に解決する必要があり、これが Nuxtでrouteに応じてVuex Storeをmodule分割する方法 - あーありがち(2018-04-19) の registerModule と矛盾していた。

もう一つは route レベルでない場合は単純に難しいということ。

cf. ルーティングとコード分割 &#183; GitBook

Nuxt で route が解決されたあとに Page component レベルで dynamic component を使って route を偽装しようとするのは可能だが、問題が複雑すぎた。

Nuxt に頼らず自前で router を直接記述しつつ Vue + SSR を実現できるならイケたかもしれないが、Page component を利用しつつ routing を差し替えるには、実は routes を直接書き換えてしまえばよいことが分かっているので、今さらわざわざこの方法を採用する必要もないだろう。

JavaScriptでRubyのArray#replaceのようなことをしたい - あーありがち(2018-04-26)

nuxt.config.js の

router: {
  extendRoutes(routes, resolve) { // <- この routes ね

store と asyncData

サーバサイドでも生かすには root component の asyncData を使う。 こうすることで route から特定の処理を挟んで store に落としてこれをクライアントサイドで利用することができる。

root component の asyncData 内で store.registerModule する方法もあるが、その場合は destroyed で解放しておかないとクライアントサイドで二重に register しようとして壊れる。

ただそもそも data reactivity を component をまたいで実現しつつ persisted にしたい（要は store を localStorage などに保存したい）とかいう場合はサーバサイドで動く意味がなく、asyncData の利用は検討外と言ってよいだろう。

個人的まとめ

今回最後の store 辺りで散々苦しんだが、理屈は分かっていなかったが、動作から逆に導いて結果として正しい選択をすることはできたみたいだ。

Vue.js の SSR について理解しないままなんかできるっぽいよという理由で Nuxt で書き始めてハマって分かったことは、SSR 固有のエラーかどうかはログを見ても知識がないとさっぱり分からないということ。

ということで自分でゼロから書かなくても公式の SSR のドキュメントは読んでおこう、という当たり前の話に戻ってきました。おしまい。

CTUのファームウェアアップデートをした

出かける直前に＞＜

  1. 突然自宅サーバの DNS サーバが一部のゾーンだけ名前解決できなくなる
  2. CTU のランプの点滅に気づく
  3. 何の更新だろうと思って調べると1ファームウェアのアップデート
  4. 確かこいつ普通に DNS 引いて TCP/IP で外出て接続した先に管理画面あるんじゃね？
  5. WiFi ルータ越しだし、今 DNS （一部）引けないですけど？

ぷちパニック。

  1. 深呼吸。
  2. そうか、有線で直結して DHCP を受け取ればイケるか？
  3. OK
  4. ブラウザから再起動ボタン押した。WiFi ルータがネットワーク接続をロストしたのを確認。
  5. 待つ。
  6. 復活！

※ できれば自動で、最低でも単体でアップデートできるようにしてくれないかなぁ。

  1. ググったりはできる ↩

EvoのExifデータが貧弱すぎる件

Singapore 用に Exif データを引っこ抜いて CSV ファイルを作る自作のツールがあるんだけど、そいつが Evo の撮ったデータに挑んで玉砕していた。なんだろうと思ったら

Evo の持ってる Exif データが想定外に貧弱

だったことが原因だった。

ほとんど

  • 生の焦点距離
  • ISO感度

くらいしか情報がない。35mm換算の焦点距離とか、絞りとかシャッタースピードとかさっぱり分からない。すごいなぁ。

事故ってた

片付いたので本来の日記らしい日記として書き起こし。

田舎で車を運転していたら後ろから追突された。状況は長い直線の途中の右折待ち。つまり自分は停車できたが後ろの車が停車できずにごつんといった。

  • 長い直線の途中の右折待ち
  • ただし停車直前にごく小さな橋があり、アップダウンがあったため、気づいたタイミングが遅い場合は止まりにくかった
    • ダウン時に踏んでも無理。アップ時に踏まないと。
  • ぶつけてきたのは若葉マーク

ぶつかる瞬間はミラーで見えていたので覚悟はできていたが、まともに運転中にぶつけられたのはほとんど初めてだったのでちょっとびっくらこいた。幸い、2台合わせて乗車5人のうち誰にも怪我がなかったのでただの物損事故で処理でき、非常に簡単に済んだのが幸いだった。

が、反省点も。

  • 急いでいたのと人身事故じゃなかったのと、まったく問題なく自走できたので警察への報告を後回しにしてしまった

個人的な状況としては本当に急いでいたのだが、お互いに近所に住んでいるならともかく、そうでない場合は呼びつける必要があるのでこれはあまり良くなかった。すぐに警察に電話しておいた方がよかった。現場からなら逆に警察に来てもらってすぐに済んでたかも。

相手が初心者でとても若かったのでいったん落ち着いてもらうという意味はあったかと思うし、自分も保険屋と話してみるまで、正直なところ段取りが吹っ飛んでいたという理由もあった。しかし二度手間は二度手間。保険屋と警察はセットで覚えておこう。

  • せめて保険屋の連絡先はすぐに分かるように携帯の電話帳とEvernoteに入れておこう

と思った次第であった。

Mechanize の parser を Hpricot にする

現状自分は Hpricot 依存のコードがいくつかあるんだけど、parser 切り換えの方法がいつも分からんくなる。

ということでメモ。この辺を見ればいい感じ。

require 'hpricot'
WWW::Mechanize.html_parser = Hpricot

して、あとはいつものように

WWW::Mechanize.new

する。

OSX のパスワード周りをやっと理解し始める

まだ続く休日なのにお仕事シリーズ。

自分では使っているけれども、これまでクライアント管理の対象に OSX は入れていなかった。これではいかんということでとりあえず OSX のアカウントについてお勉強。

  • root ユーザー（Windows では Administrator に相当するか？）はデフォルトで無効
    • ただし sudo を利用できる管理者アカウントというものがある。管理者アカウントでの作業も通常はそのユーザーの権限で行われる。
  • Netinfo マネージャから root アカウントを有効にすることもできるが、ログインウィンドウに root というユーザーが並ぶことはない
  • マスターパスワードは管理者アカウントのパスワードを忘れても FileVault に対しては有効だが、ログインパスワードとしては機能しない。

管理者アカウントのパスワードを忘れてしまったコンピュータで管理者権限を必要とする作業を行わなければいけない事態1が想定される場合、

  • root ユーザーを有効にしておく
  • パスワードリセットで乗り切る

のどちらかになるのかな？ FileVault を使う場合はマスターパスワード必須なんだろな2。これを使うべきかどうか。うむ。

cf. アップル - サポート - Mac OS X v10.4 Tiger - アカウント、パスワード、セキュリティ

ふー。これで宿題はとりあえず終了だろう。

  1. 自動ログインになっている場合によくありそう。 ↩

  2. マスターパスワードってリセットできるの？ ↩

Unix での日本語ファイル名の扱い

予想

  • FreeBSD では jls と jmsdos という ports がある。
  • FreeBSD の ls は GNU ls じゃないので多言語化されていないのでは？
  • したがって普通に日本語のファイルを作成するのは基本は NG.
  • jmsdos はカーネル用のダイナミックドライバ(?)と mount コマンド用のオプションを提供するもの。これも Linux の mount、カーネルとは別ものなので、追加の必要あり。

で、この辺のツールは最近の Linux ディストリビューションではユーザーは何も意識しなくても使えるようになっている。

のではなかろうか？

samba の日本語ファイル名も WebDAV の日本語ファイル名も適切に設定してあれば日本語 EUC のファイル名で保存するので、そっから先は ls も terminal も shell も無問題なのではないかな。

FreeBSD では shell と terminal はともかく、ls ではコケそうな気がする。

JMeter

ほほー。Java で書かれていて POST のパラメータを渡せる GUI なパフォーマンステスタですか。よさげですな。ab もシンプルなチューニングには有用なんだけど、form が絡むとなかなか面倒だしね。

実験は休みが明けたらやる。

portable ZebedeePortForwarder & IRC 環境

以前 USB メモリに ssh 環境を作って遊んでいたが、今度は Zebedee & IRC 環境を作ってみた（Windows Only）。IRC は単に設定済みのクライアントを放り込んであるだけ。Zebedee はバッチファイルから起動する以外に方法がないので、プロンプトのウィンドウが残るのが気持ち悪いが仕方がない。

しかし Zebedee を kill しないと USB メモリを（原則）抜けないってのがちょっと分かりにくいなぁ。Zebedee やめて portforwarder にしようか？ その方がマシかもなぁ。。。

その方向で決定。

おっと cookie 漏れてないですか

アングラサイトを徘徊したりしてないので個人的にはあんまり関係ないのですが、とりあえずメモっておこう。こういうのは IE コンポーネントタブブラウザであやしげなところを徘徊している人たちにいろいろノウハウがあるんでしょうが、自分は今のところ Mozilla の Cookie Manager 以外にはツールがないです。なんか探した方がええのかな。

Opera はローカルのファイルを読み取られちゃいます

Mac版 IE 5, Office 98 サポート終了ですか

http://slashdot.jp/article.pl?sid=03/04/28/0156207

うーん。いよいよ Classic は捨てろというような感じになってきましたねぇ。どうやって捨てるか、それが問題でしょうなぁ。eMac でも G4 だからとりあえず OS X を使うにはいいかもしれないけど、eMac, iMac はモニタを選べないという致命的な問題を抱えているし、ポリタンクは一気に値段が上がるし…。

About

例によって個人のなんちゃらです