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

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

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

文書を“作る”

この記事を読む皆様は、少なからず日頃から文章を書くことがあるかと思います。 文章を書き公開しようというとき、「良い文章の書き方」はいろいろなところで目にしますし、必要とあらば勉強することもあるでしょう。

しかし、文章そのものではなく「良い文書の作り方」を意識したことはありますか？ どんなに良い文章であっても、駄目な性質を多く持つ文書として公開されると、その価値は暴落します[0]。

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

良い文書とは

私の考える良い文書とは何なのか、以下で例を出しながら紹介します。

永続的にアクセス可能

これはある意味で、 web に (無論それに限りませんが) 情報を公開するうえで最も重要な性質です。

たとえば、私の書いた記事を他の人が引用したり、リンクして参照したりするかもしれません。 数年後 (あるいは十数年後) になって私のその記事が消えていた場合、もはや引用や参照を行った記事の正当性を確信することは難しくなります。 引用されていればまだマシで、リンクしか行われていなかった場合、正当性どころか情報の有効性さえ失うかもしれません。

リンク破綻は、直接・間接問わず、何らかの情報を参照していた多くの文書の価値を同時に低下させるものです。 あなたが他人の文書の価値を低下させないため、ひいては web 全体の有用性を低下させないために、一度公開された文書は (余程の理由がない限り) できるだけ永続的に、同じ URL で公開していくべきです。

また、ここで「私の文書は適当に書いたものであり、参照するに値しない」と主張する著者もいるかもしれません。 しかし、文書を参照するか決めるのは著者本人ではなく、引用者など別の人です。 どんな駄文であっても、著者が考えもしなかった観点で活用されるかもしれず、そうなったとき著者が「この文書に価値はない」といって公開を取り下げることで間接的に他の (有用かもしれない) 文書まで価値を落とすのは、あまりに勿体ないことです。

何をすべきか

  • 文書を公開したら、それをできるだけ公開しつづけること。
  • web ページであれば、 URL を変えないこと。
    • 仕方なく URL を変えたなら、リダイレクトを永続的に設定すること。
  • もし公開しつづける自信がないなら、引用やコピー、再頒布を明示的に許可すること。

反面教師

マスコミ各社の web ニュース記事

記事が公開されるのは大変結構ですが、しばらくたつと公開が取り下げられているのはどういうことでしょうか。 多くの人々が (本文の引用でなく) URL によってニュース記事を参照しますが、ニュース記事が削除されると、それについての言及のほとんどは精密さを欠くか、何を言っているのかわからない状態になります。

マスコミは、組織や業界として社会や人々にそれなりに大規模に影響を与えていながら、その証拠は容易に参照できないよう人々の手から取り上げることを、恥ずかしく思わないのでしょうか。 品性を疑います。

アドバイス: マスコミのニュース記事に言及するときは、関係する本文を容赦なく引用しましょう。引用するべきです。

CMS

CMS (Content Management System) は、それぞれが独自の URL を用いていることが多いため、 CMS を乗り替えようとすると、大抵記事の URL が変化します。 これは非常によくないことです。 特に、サイトの構造や記事集合が変化していないにも関わらずリンクが切れることなどがあり、その場合記事が削除されたのか、またはどこか他の場所に移動したのか、はたまたサイト自体が別物になったのか、閲覧者が判断することが困難になることさえあります。

CMS はこういった問題を比較的起こしやすいため、安易に CMS を使うのは避けるべきです。 CMS を使うのであれば、記事の URL や URL 規則を柔軟かつ簡単に指定可能なもの、かつ、リダイレクトを設定できるものを選ぶべきです。

URL の柔軟な指定や処理系間での維持しやすさでは、静的サイトジェネレータと呼ばれるものが秀でており、 CMS で敢えてサーバ側でコンテンツ生成や管理を行う必要がないのであれば、まず静的サイトジェネレータの利用を検討するべきでしょう。

良い例

ITmedia

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

公開・更新日時がわかりやすい

そのままです。 outdated な情報をそうと明示せず公開するのは危険です。

本当は「腐ったら腐臭を発する」という仕組みにできれば安全なのですが、一度公開した記事が古くなったか継続的に確認するというのは、著者にとってかなり負担の大きい作業になり、生産性もありません。 妥協点として、「賞味期限を書いておくから、イケるか無理かは読者が各自で判断せよ」とするのがバランスがとれていて良いでしょう。

記事の公開・更新日時は、記事末尾に書いてあるようでは読者に不親切です。 記事を読む前に、それがどのくらい古い情報なのか把握できるべきですから、それらの情報は文書の先頭近くに表示されるべきです。

なお、 outdated になったから (或いは、なる前に) 記事を取り除く、という戦略は愚行であり有害です。 『永続的にアクセス可能』節を参照。

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

皆様はどのような言語、どのような形式で文書を書いていますか。 文書形式として、 markdown, AsciiDoc, DocBook, plain text, OpenDocument, Office Open XML, HTML, TEI, LaTeX, その他多くの形式が知られています。 これらの中で、或いは他のあらゆる形式で、どれを使うのが望ましいのでしょうか。

長く利用しやすい文書を作るうえで、いくつか欲しくなる性質があります。

  • ソースとして欲しい性質
    • 他フォーマットへ変換しやすい
    • 充実した語彙
    • 一貫した文法
      • もう少し贅沢を言うなら、機械で処理しやすい文法
  • 出力フォーマットとして欲しい性質
    • リンクなどの機能
    • 数式や画像などの埋め込みやインライン表示

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

この性質があると、たとえばより良いフォーマットを見付けたときや、使っていた処理系がメンテナンスされなくなったときなど、他形式への移行がしやすくなります。

また、入力フォーマットがこのような性質を持っていると、出力形式を選びやすいというメリットもあります。 たとえば普段は HTML に出力しているが、あるとき TeX で PDF 出力したデータを欲しくなった、などの場合に、ソースが変換に使いやすいものだと楽ができます。 (まあ、 pandoc のような高度なツールが対応していればどうにかなる場合も多いのですが。) 一般に読むより書く方が簡単なので、入力形式として (機械にとって) 良さげなものを選んでおけば、出力形式に使いづらいということはないでしょう。

充実した語彙

たとえば LaTeX で何事か書いているとき、独自にマクロを定義することがあるかもしれません。 こういったマクロを使うと、単なる見た目のみならず言葉や文章が持つ意味なども指定することができます——少なくとも文書内では。

また、 HTML を書いていても、 class 属性などを使って、要素の意味や役割をタグ名よりも細かく指定することができます。 しかしその値と意味は、 HTML で文書を書いている人や文書を処理する人々全体で合意されたものではありません。

こういった独自定義の語彙は、文書内では、また著者にとってはある程度一貫した意味付けがされています。 しかしこれを他人や外部プログラムが見たとき、その意味を正しく理解することは容易でないかもしれません。 特にプログラムにとっては、意味とはロジックに組み込まれる形でサポートされがちなものです。 ドキュメントごとにバラバラに自然言語で指定された何らかの名前から、その扱いを適切に推測するというのは一般に困難になります。 つまり、意味についての知識が機械可読な形で表現されていないということです。

Markdown

この観点では、 markdown はほぼ駄目です。 語彙として用意されている「意味」は極めて原始的であるか、そもそも「意味」の指定のない表示スタイル指定がほとんどです。

HTML

HTML (特に 5 以上) は、タグも増え、また CSS によって表示スタイルを分離された結果、だいぶ多くの「意味」をそれなりに綺麗に表現できます。 ただ、文法が XML よりも汚いうえ、 HTML 標準で用意したよりも細かい意味については class 属性や CSS による表示の区別を前提としている面があり、機械的な処理には使いづらくなっています。

具体的な例をひとつあげると、 HTML では脚注を意味する要素は存在しないため、何らかの class 属性などを設定したうえで JavaScript で処理してやるか、事前に「[1]」などのマーカーと記事末尾の脚注を別々に書いておくなどの必要があります。 その際、マーカーに使う文字列と記事末尾に書く文字列は、独自の属性で指定して CSS で表示させるか、手動で同期する必要があります。

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

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

LaTeX

データというより半ばプログラムなので、機械的な処理は難しそうです。 処理系を書いたことがないのでわかりませんが。 少なくとも、私は LaTeX 文書をソースに使おうという気持ちにはなりません。

私の好みはさておき語彙についてですが、 LaTeX のマクロは文字通りマクロなので、人間に対しては意味を表明しているように見えるかもしれませんが、機械から見てその意図を正しく把握するのは難しそうです。 すなわち、「どうなるべきか」と「どういうものか」が分離できていないということで、マクロは後者というより前者の機能が強く出ているように思われます。 マクロは独自定義や再定義も簡単に可能であり、たとえ広く使われるライブラリのようなものがあっても、マクロ名からその意味を取り出すのは簡単ではないでしょう。

XML

XML 系の形式は、この問題について特異な解決策を提示しています。 名前空間と XSL です。

名前空間は、外部で定義された語彙を文書へ取り込んで使うことを可能にします。 たとえば DocBook 内に SVG 画像を埋め込んだり、 MathML で数式を埋め込んだり。 他にも、独自定義の語彙も、専用の名前空間を用意して一意に区別させることができます。

XSL は、文書で使われる語彙の意味そのものを表現するのではなく、語彙同士の変換を可能にします。 たとえば DocBook の語彙を HTML の語彙へ変換したりできます。 ある語彙から別の語彙への変換を、処理系が直接サポートせずユーザが書けるようにすることで、処理系が意味を理解することなく「意味を理解していたら行ったであろう変換」のロジックを実行できるようにするのです。

この名前空間と XSL の組み合わせによって、以下のようなことができるようになります。

  • 使用されている語彙が既知であるか、処理系自身が機械的に判断可能
  • 語彙の追加が、文書の互換性を極端に損ねない
    • タグが未知であっても XML という構文が共通のため、単にタグの存在を無視する (タグが何も意味していないとする) ことによって保守的に処理可能
  • 未知の語彙について、語彙の作成者や利用者が用意した (文書とともに用意された) XSL スタイルシートを参照することで、意図された変換を把握したり利用できる
    • XSL を使わないとしても、 XML という構文が共通のため、処理系に対して拡張を行いやすい
  • 複数の語彙を必要なだけ組み合わせて利用可能

こういった理由から、 XML は文書の内容に意味を付与する方法としてはかなりマシな選択肢であると思われます。

静的である

動的でないこと。 すなわち文書を閲覧するとき決まったデータが存在するだけで、ロジック (プログラム) ができるだけそこに介在しないということです。 もっとはっきり言えば、標準化されていない専用のビューアなどを必要としないこと[3]、また JavaScript のようなスクリプトを実行する必要がないことです。

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

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

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

変更が明示される

全ての参照が必ずしも完全な引用によって行われるとは限りません。 リンクなどによって参照が行われた場合、リンク先の文書の内容を著しく改変することは、参照元の文書まで破壊することに繋がります。 大きな変更や重要な変更を行うのであれば、その内容や変更前後での違い自体について、何らかの情報や告知が (当該文書内に) 残されるべきです。

たとえば HTML などであれば del 要素や ins 要素によって、機械が判別可能な形で、一部分の削除や挿入を示すことが可能です。 さらに CSS を使えば、ユーザが認識しやすいように表示することもできます。 もちろん、大規模な変更については、こういったタグを使わず、専用のセクションや aside 要素などによって文書の変更について説明することもできます。

反面教師

マスコミ各社の web ニュース記事

記事が公開されるのは大変結構ですが、記事の内容がサイレントに丸ごと書き換えられていたりするのはどういうことでしょうか。 多くの人々が (本文の引用でなく) URL によってニュース記事を参照しますが、ニュース記事が大きく改変されると、それについての言及のほとんどは精密さを欠くか、何を言っているのかわからない状態になります。

マスコミは、組織や業界として社会や人々にそれなりに大規模に影響を与えていながら、その手法や自分のしたことは容易に追跡できないよう工作することを、恥ずかしく思わないのでしょうか。 品性を疑います。

アドバイス: マスコミのニュース記事に言及するときは、関係する本文を容赦なく引用しましょう。引用するべきです。

私は何をしているか

永続的なアクセスの提供

これは正直難しいですが、まあ地道に頑張るしかありません。

技術的には、たとえば CMS を使うのではなく静的サイトジェネレータを使うことで、 URL を素朴にし、維持しやすくしています。 また、年月日で階層的にディレクトリを作って範囲を細かく切ることで、ある時期から URL 規則を変化させたくなったとしても、過去の記事の URL に与える影響が小さくなるようコントロールしています。

ドメインも www.〜 でなく blog.〜 を使うことで、ブログ専用で使える名前空間を確保し、ブログでない情報で行う変更の影響を受けないよう隔離してあります。

セクション単位の ID の手動指定

このブログ記事のセクションのタイトルにマウスカーソルを乗せる (スマホならタップする) とわかると思いますが、すべてのセクションに手動で ID を付けており、またセクションへのリンクの URL を取得しやすくしてあります。

理想的には、記事中に埋め込んだ画像やコードなど、セクション以外の何らかの塊についてもそれぞれ ID を割り振りたいところですが、忘れがちです。 (まあ、自動化されて不安定な ID が勝手に発生するよりはマシだと思うことにしています。)

公開・更新日時を記事先頭で明示

ページの頭で、記事の公開日時や更新日時を表示するようにしています。

記事の更新については、誤字脱字やスタイル変更などは更新とは見做さず、内容に意味的な変更や追加があった場合に更新日時を変化させるようにしています。

ソースコードに意味付けする

少し前までの記事は、 HTML をベースにいくらかの独自の語彙 (セクションレベル非依存のセクションタイトル、脚注、クロスリファレンス、絵文字参照、 SNS の投稿引用など) を加えた XML 形式を利用しており、 XSLT によって XHTML5 (HTML5 の一種) に変換していました。 この形式は、 HTML の語彙を前提にしつつ、 HTML では (私にとって) 不足していた語彙を追加したものです。 独自に定義した語彙を潰して (あるいは人間にとって意味ある構造に変換して) HTML にすることで、 web ページを生成します。

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

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

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

独自拡張 HTML は、まあ HTML なので別形式への意味を保ったままの変換は難しいでしょう。 できるとしても精々が、文書構造を保ったままの変換といったところです。

DocBook は、 (その界隈では) 広く知られた形式であり、たとえば pandoc なども対応していますので、変換はしやすいでしょう。 たとえば AsciiDoc などは DocBook の文書構造を参考に作られたもので、 DocBook → AsciiDoc の変換なども難しくないはずです。 どうしてもツールが対応していない形式にしたいというのであれば、自分で XSLT スタイルシートを書くこともできますし、 XML ライブラリを使っていろいろな言語で処理ツールを書くこともできます。

DocBook は割と意味がはっきりしている部類なので、語彙の少ない大抵の形式にはそう苦労することなく変換できるはずです。

静的である

このブログは極めて静的です。 nginx によってファイルが配信されており、そのファイルは静的サイトジェネレータによって生成されたものがそのままサーバに置かれています。 また、ページを閲覧するのに JavaScript を必要としません 。

ページ末尾にある共有ボタンなどは、正直要らない気がするしプライバシーについての懸念もあるので、そのうち削除するかもしれません。 Twitter のツイートの引用も、 (スクリプトなしでも閲覧はできますが) スクリプトのロードを要求している部分なので、実は気に入っていません。 そのうちなんとかするかも[5]。

変更の明示

明示しましょう。 それだけです。

明示しやすくするための仕組みとして、 admonition block というのを使っています。 たとえば DocBook でいう important 要素とか note 要素とか warning 要素とかです。 独自 HTML にも、これに似た仕組みは導入して使っていました。

まとめ

  • 良い文章の書き方だけでなく、良い文書の作り方を気にかけてみましょう。
    • 永続的にアクセスできるよう、 URL を固定してしっかり維持しましょう。
    • セクションごとに手動で固定の ID を割り振り、しっかり維持しましょう。
    • 公開・更新日時はしっかり表示しましょう。
    • 機械にとってもよく意味付けされた文書を書くようにしましょう。
    • 静的でよい文書は静的にしましょう。
    • 変更は明示しましょう。
  • 文書フォーマットをよく選びましょう。
    • markdown は微妙なので良い文書を書くのに使うべきではありません。
      • Wiki などで markdown を使っている場合は、長期的なデータの持続性や互換性、外部からのリンクの維持に疑念があるので要注意です。
    • HTML5 はかなりマシではありますが、これもどちらかというと出力寄りです。
    • LaTeX は人間にとってはよく意味付けされているように見えるかもしれませんが、機械にとってはそうでもありません。
    • DocBook 5 はイケてます (個人の感想)。 そうでなくとも XML ベースだと割といい感じに調整しやすいです。

参考