XENEXE

技術系のブログ記事を執筆する際に注意しているポイント


heroImage

1. はじめに

技術系のブログ記事を執筆するには,ですます調・だである調を統一するや,事実と意見を区別するなどの一般的な情報リテラシーと技術系のブログ記事特有のポイントが存在します。本記事では,筆者が技術系のブログ記事を執筆する際に注意しているポイントについて記述します。

2. 引用元を明確に記載する

参考にしたドキュメントやネット記事は,読者が引用元を辿れるように記載します。一般的な学術論文のように参考文献として記載しても良いのですが,HTML の利点を活かしてブログ記事の場合はリンクとして埋め込みます。例えば,Python のチュートリアル記事を執筆すると仮定する。その際に,公式のチュートリアルページを参考にしたならば “公式のチュートリアルに従って○○○する” と記述します。一般的な学術論文とは異なり,ブログ記事には Wikipedia や YouTube などの情報も記載することができるので,読者が効率よく引用元を辿れるように情報を埋め込みます。

3. 環境情報を記載する

開発環境の構築やプログラミングなど,ソフトウェアのバージョンによって手順が変わるブログ記事には執筆者自身の環境情報を記載します。その際,筆者は依存度が高いものだけを記載するようにしています。例えば,Python に関する記事の場合。OS や Python 本体のバージョンは重要ですが,Python をコーディングする際に使用したテキストエディターのバージョンは不要です。

また,なるべくレイアー別に記載するように心がけています。例えば,Bootstrap に関する記事を執筆した場合,OS → ブラウザ → ライブラリと抽象度順に記載します。

4. 再現性のある記事を執筆する

プログラミングに関するブログ記事の場合,ソースコードと実行結果を記載するだけではなく,実行に必要なライブラリのインストール方法や実行環境の構築手順なども記述します。必要な手順が多い場合は,外部のチュートリアル記事やネット記事を引用するようし,執筆者自身と読者の実行結果が同じになるように心がけています。

5. おわりに

ここまで,筆者が技術系のブログ記事を執筆する際に注意しているポイントについて記述してきました。技術系のブログ記事は,一般的な理系の学術論文にも繋がる部分が多くあります。良い文章を書くには執筆と推敲を繰り返すしかないので,アウトプットの習慣が重要です。