はじめに

こんにちは。テスト自動化アーキテクトの牧野です。

私が技術ブログで使用するワークスペースの構築について紹介します。私はブログ記事をマークダウン形式で執筆します。この記事では、その際に使用するワークスペースの内容、必要な機能、およびそれらを実現する方法について説明します。

環境

本記事ではエディタとしてVSCodeを利用し、スクリプトの実行環境としてbashを用いています。

目的

目的は、マークダウン形式で快適に記事を執筆し、いくつかの形式で提出できることです。以下が求める機能です。

マークダウンとはHTMLを始めとした整形済み文書を作成するための記述方法であり、見出しや強調、リストなどを比較的に簡潔に記述できます。一般的に拡張子は.mdが用いられます本記事の.mdファイルがマークダウンだと理解していただけると読みやすいでしょう。

1. 構造化

• 項目ごとにフォルダやファイルを作成できる。

• 提出物に含まない付録や資料を保存できる。

2. レビュー

• レビューしたい場所や内容をメモできる。

• レビューしたいポイントを一覧化できる。

3. 製本

• マークダウン形式で提出するファイルを作成できる。

• その他の形式にも対応できる。

ファイル構造

ワークスペース内のファイル構造は以下のようになります。

├─1.intro
│      1.hello.md
│      2.motivation.md
│
├─2.about
│      1.notice.md
│
├─3.main
│      1.wao.md
│      2.amazing.md
│      3.foo.md
│
└─4.fin
        1.bye.md

好きなフォルダを追加したり、資料用のファイルを含めても構いません。提出するファイルの選定については後述の「製本」で行います。製本にて提出するファイルを選定することで提出物を限定でき、ワークスペースに自由に資料や付録を配置できます。

ポイントとしては記事の順序に従いファイルをナンバリングすることです。ナンバリングにより各ファイルの順序を指定でき、文書構造が分かりやすくなり、後の製本の際にも役立ちます。

目次からこの構造のディレクトリやファイルを生成するスクリプトを用意してもよいかもしれません。

ReviewMeでレビューポイントをメモ (ReviewMe)

レビューしたい場所をメモするために、//ReviewMe レビューして欲しい事 といったフォーマットでメモを残します。

ブログを書くのには素晴らしいワークスペースが必要
//ReviewMe 素晴らしいとは？

このようにメモを残すことで、後で簡単にレビューポイントを抽出できます。また、//ReviewMe という単語を使用することで、メモを見つけやすくし、他の単語との競合を避けています。

レビューポイントの一覧化 (適当grep)

レビューポイントを一覧化するために、次のようなコマンドを使用します。

grep -r -n ReviewMe ./

出力例:

./1.intro/1.hello.md:1:// ReviewMe:気の利いた挨拶
./2.about/1.notice.md:4:// ReviewMe:いい感じに注意
./3.main/2.amazing.md:2:// ReviewMe 感動的すぎないか？
./3.main/2.amazing.md:7:// ReviewMe もっと感動的すぎないか？
./3.main/3.foo.md:1:// ReviewMe barbaz

このコマンドによって、各ファイル内のレビューポイントが一覧化され、効率的に確認できます。

マージリクエストでレビューを受ける

ワークスペースの利用とは少し異なりますが、Gitlab等のマージリクエスト(GitHubのプルリクエスト)を使用してレビューを受けることもあります。

Gitlabのマージリクエストのコードレビュー機能を活用し、エンジニアがよく行うコードレビューと同様のレビュー手順を実施しています。

Gitlabのレビュー機能は、Issueの作成、マージリクエストの作成、ブランチの作成などが簡単に行えるため、レビュー結果の保存や次の作業を始めるのに非常に便利です。

また、レビューの際には先のレビューポイントの一覧により作成したレビューサマリーを提供することで、円滑なレビュー・コミュニケーションを狙います。対面でのレビューも行うことができますし、非同期でのレビューも可能です。

製本

作成した原稿から提出用のファイルを作成する作業を「製本」と呼んでいます。

記事の製本を行う方法はいろいろありますが、多くの場合簡単な連結操作を行います。

mkdir -p dist
rm dist/*

ls 1.intro/* | xargs cat >> dist/1.intro.md
ls 2.about/* | xargs cat >> dist/2.about.md
ls 3.main/* | xargs cat >> dist/3.main.md
ls 4.fin/* | xargs cat >> dist/4.fin.md

cat dist/*.md >> dist/readme.md

これにより、ブログ記事として提出するために、すべてのマークダウンファイルが一つのファイルに結合されます。今回はGitlabで即座に確認しやすいようにreadme.mdとして作成しています。

フォルダごとに連結することで、章ごとのファイルを簡単に生成できます。シェルスクリプトはBashやWSLを使用することで、Windows環境でも適切に動作します。必要に応じてPandocなどのツールを導入し、異なる形式への変換にも対応することができます。

製本に含まないファイルはこのスクリプトでは触れません。必要なファイルだけを使うことで、付録や資料を除外することができます。

これらの手法を使用して、ブログ記事の執筆、レビュー、および提出を効率的に行ってみてはいかがでしょうか。

★★SHIFT公式ブログでアドベントカレンダー★★
明日の記事は、
『目指せ言語化マスター！チームで言語化トレーニング（抽象化・具体化の練習）を実施してみた』
お楽しみに！

お問合せはお気軽に

SHIFTについて（コーポレートサイト）
https://www.shiftinc.jp/

SHIFTのサービスについて（サービスサイト）
https://service.shiftinc.jp/

SHIFTの導入事例
https://service.shiftinc.jp/case/

お役立ち資料はこちら
https://service.shiftinc.jp/resources/

SHIFTの採用情報はこちら　

PHOTO：UnsplashのKarl Pawlowicz