技術文書を書く参考になれば・・・

そろそろ Juno を更新したいけど、いろいろいじっていたら収集がつかなくなりかけてきてる。HttpProxy とかまた実装しなおしたし。。。というわけで普通っぽい記事をちょっと書いてみる。

仕事柄、プログラムの仕様書とか手順書とかを書くわけだけど、やっぱり人によって言葉使いが違う。「クリックする」を無理やり「押下する」とか書いてるけど、実際にクリック イベントが発生するのはボタンを離した時なんだよなぁ、、、とか思いながらレビューしてる。こんなモヤモヤはできれば解消したいので、自分が普段参考にしてる資料を共有できたらなぁと。


言わずと知れた Microsoft は、実は自社製品のドキュメントを書く際の方針を公開している。自分がドキュメントを書くときは、このサイトからダウンロードできるスタイル ガイドをベースに、細かい訳語を随時調べながらやってる。このガイド、昔は日本語の HTML ヘルプ ファイルだったのに、今は英語の PDF になってるんだよなぁ。ちなみに会社のファイル サーバーには昔のバージョンが置いてある。

Wikipedia:表記ガイド - Wikipedia

ついこの前見つけたんだけど、Wikipedia のマニュアルも結構細かくまとまってる。環境に合うものを選んで採用するのもいいかも。

全角英数について

これも個人的には大きな問題だと思ってる。下の例を見れば一目瞭然だと思うけど、全角英数を使ってしまうとワード ラップが効かず、単語の途中で折り返されてしまって死ぬほど読みにくい。

  • 全角英数

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

  • 半角英数

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

全角英数イクナイ!!

フォント

フォントもちゃんと選ぶべきだと思う。たとえば MS UI Gothic なんかは、その名が示す通り UI 向けのフォントだから文章には向かないと思ってる。ひらがなの形がなんかチャラくて好きじゃないし。あと、文脈によって変えるべき。コードやコマンドを書くなら等幅フォントのほうが絶対に読みやすい。Word を使うときは、そのためのスタイルを作って使うようにしてる。普段使っているフォントはこんな感じ。

文脈 和文 英文
普通の文 MS Pゴシック Calibri
コード MS ゴシック Consolas または Courier New