環境構築してみた系の記事を書くときに気を付けていること
概要
先日F* のインストール+実行可能コード生成までの手順(2022年)という記事を書きました。この記事では F* という言語の開発環境を整えるための、再現可能な手順を紹介しました。
この記事では、環境構築系の記事を書く際に、読者にとって有益な記事とするために私が気を付けていることを紹介します。
読者が追走可能なようにする
記事執筆者と読者の間で環境が異なっていた場合、同じ手順を実行しても同じ結果が得られないことがあります。
そのため、どのような環境を用いたかを明記して手順の再現可能性を高めることが重要です。
使用した環境・アプリなどのバージョンが何なのかを記載する
先日の記事内で参照しているログでは、自分がどのような環境で実験したかを書き残しています。
事実だけではなく、それをどのようなコマンドで取得したかも明記する
上のリンク先では、環境のバージョンをどのコマンドで取得したかも記載してあります。
取得コマンドを明記することによって、事実に根拠が与えられるだけではなく、同じ手順で容易に読者が事実を集められるようになります。
なるべく再現しやすい初期状態の環境を用意して、そこから作業を開始する
自分が普段使っているマシンは初期状態からいろいろと使い込んだ後の状態になっていることが多いと思います。
この状態では、読者が同一の環境を構築することが容易でないうえに、自分のおこなったどの設定・インストールが手順の結果に影響したかが不明瞭であるために情報自体の価値も揺らいでしまいます。
そのため、可能な場合はdocker image などで再現可能な初期状態を用意し、そこからの差分という形で手順を書きたいです。
前回は、VSCode dev container 機能で用意される Ubuntu イメージからスタートする手順にしました。
作業が順調に進んでいるかどうかを確かめるための手順を細かく挟む
なんらかの理由で 1 step が失敗していたとしても、それを確かめる手順がなければ最後まで手順をなぞった後に異変に気付くことになりかねません。
そのため、意味のある手順の単位ごとに、その手順が順調に進んでいるかを確かめる確認用の手順を挟むとよさそうです。
意味のある手順で確認作業が挟まっていれば、追走している読者は「うまくいかなかった箇所」を特定しやすくなり、自力で迂回策を見つけやすくなるかと思います。
手順が妥当である根拠を提示する
自分が提示する手順が妥当である根拠を読者に与えることも重要です。
これによって手順を信頼してもらえるだけではなく、根拠となる前提が違った場合に追走者が手順を一部差し換えたりすることが容易になります。
どこに書いてある手順をもとにしているかを明記
参考にした手順がある場合には、それを明記します。
自分で手順を考案/改変したところは、なぜその手順にしたかの根拠を明示する
前回の例だと、参考にした手順をそのまま走るとインストールに失敗する箇所があり、そのため一部手順を修正する必要がありました。
そこに対して「なぜ修正したか」の説明を加えています。
まとめ
環境構築系の情報提供記事/ドキュメントを書くときに、筆者が気を付けている点を挙げました。
他に気を付けている点などがあったら是非コメントしてみてくださいね！
Discussion
私自身はそういった種類の記事を書くことはあまりないのですが、読む立場で気にかかるのはインストールしようとしているものについての説明が最初にない場合があることです。 例に挙げられた F* の記事で言えば F* をインストールしようとしているというところから文が始まっていて F* が何であるか言及がありません。
すでに F* に興味を持っている人に対して具体的な手順の補助になるようにという意図であればそれでよいのですが「触ってみる人が増えると嬉しい」と感じているのであれば最初の一文は F* が少なくともプログラミング言語であること (それに加えてちょっとした特徴程度) はわかるような書き方になっているのが望ましいように思います。
リンクが提示されているので詳細はそちらを見ればいいですし読み進めていけば十分に察せられるとはいえ、表題や冒頭で興味をひかれなければそもそも読みませんので……。
齊藤さま、
ご意見とご指摘ありがとうございます。
おっしゃる通り、「F* について既に興味を持っているが、インストール手順が複雑なせいでそれ以降興味を失っている人」のみを暗黙のうちに想定してしまっていました。当該分野（依存型言語)は結構マニアックであるため新規に興味を持つ人を増やすのは私の力では難しいと考え、また依存型言語について知っている人ならば F* の名前は知っていると考えてしまったようです。
今までご存じなかった方にFや依存型言語を知っていただける機会が少しでも増えるのは私の願うところですので、ご指摘いただいた通り当該記事の冒頭にF の簡潔な説明と、F* の嬉しさについて書いた紹介記事への導線を追加し、さらに記事タイトルにF* が依存型言語であることを明記しました。
改めて、ご指摘ありがとうございます。
大いに参考になります！