何とは言わない天然水飲みたさ

有用な文書を作るために心掛けたいこと

rogy Advent Calendar 2018 の21日目の記事 (#LATECH) です。 前日の記事は STM32でマウスとキーボードを作る – 東京工業大学 ロボット技術研究会公式ブログ でした。

文書を“作る”

[0]

本記事では、内容はさておき「良い文書」を作ろうというとき私が心掛けていることなどを紹介します。

良い文書とは

反面教師

15年前の記事も閲覧できます。 つまり、たとえば15年前に ITmedia PC USER の記事にリンクして何事か書いた web サイトがあったとしても、我々はそれを今読んで内容を理解したり正しさを検証したりできるわけです。 安心感がありますね。

永続的にアクセス可能』節を参照。

ソースコードがよく意味付けされている

[4]が、これもどちらかというと文書構造をより精密に指定できるようにしようというもので、フレーズなどの意味をより多彩に表現できるようにしようというものではありません。

HTML は、入力というより出力向けの形式であるといえるでしょう。

LaTeX

[5]、また JavaScript のようなスクリプトを実行する必要がないことです。

動的な仕組みは文書の解析を困難にします。 たとえば、スクリプトによって内容がロードされるページは、単純にダウンロードしただけでは文書内容を読めない場合が多く、保存や機械的な処理が極端に難しくなります。

また、ユーザ端末のリソースを余計に消費します。 たとえば、 web ページに不必要なアニメーションを沢山入れれば、それだけ閲覧者の注意力や端末の電池を消耗させます。

オレオレビューアなどは、標準化されていない限りいつかメンテナンスされなくなります。 一般に文書というのはソフトウェアよりも寿命が長くなるものですから、文書を特定のソフトウェアに依存させるべきではありません。 長生きできたかもしれない文書を、短命なソフトウェアと心中させないようにすべきです。 そのために、国際標準や広く知られたフォーマット[6]を利用しましょう。

変更が明示される

DocBook 5 で書いています。 多少の拡張を加えてあるのですが、今のところは簡単かつ単純に DocBook に潰せる程度のものです。 これからも拡張をしていくつもりですが、いずれにせよ DocBook か HTML に潰せるように作るつもりです。

実は DocBook から HTML への変換の XSLT は、公式で用意されていたもので満足できなかったため、独自に用意しました。 語彙についてきちんと定義したドキュメントが存在するからこそ、こうしてサードパーティで自分に合った処理系を用意することができるのです。

他フォーマットへ変換しやすい

[7]

変更の明示