SIOS Coatiのオンラインマニュアルの作成方法(後編)

始めに

SIOS Coatiのチームにいる高正(たかしょう)です。
みなさまいかがお過ごしでしょうか。私は先日、夏休みをとって、家族で山梨県に旅行に行ってきました。
昨年も山梨県で今年も山梨県です。特に山梨に所縁はありませんが、去年旅行に行って気に入ったので今年も山梨に赴いた感じです。山梨のおすすめスポット色々あると思いますが、私のおすすめスポットは、ほったらかし温泉です。なんでほったらかし温泉という名前であるかは公式のホームページにお任せしましょう。

私がおすすめする理由はただ一つ、景色が良いからです。ここの温泉はあっちの湯、こっちの湯と2つの温泉があります。去年はこっちの湯に入り、今年はあっちの湯に入りました。それぞれ微妙に違いがあって良いです。どのように違うかは実際に行って体験してみてください。ちなみに、天気がよければ富士山がとーってもきれいにみれるビュースポットなのですが、実は私、去年も今年も富士山を拝むことはできていません。いつの日か素敵な富士山を見たいものです。

オンラインマニュアルをデプロイするまでの流れ

前回の記事ではマニュアルの作成はSphinxを使って、マニュアルのデプロイにはBitbucket Pipelinesを使っていると説明しましたが、これらについて具体的などのようなプロセスを経てデプロイされるか説明をしたいと思います。

ざっくりとうちの開発チームにおけるデプロイまでの流れを書くと以下のようになります。

1.reStructuredText(reST)*1で書いたマニュアル用のソースコードを開発用ブランチにコミットする

2.開発用ブランチへのソースコードのコミットを契機にステージング用のS3バケットのマニュアルをデプロイ*2する

3.2のレビューで問題がなければ、本番用ブランチにソースコードをマージしてプロダクション用のS3バケットにマニュアルをデプロイ*2する

*1.reStructuredText(reST)はSphinxで採用されているマークアップ言語です。Markdown記法と似ています。Markdownを理解している方であれば、比較的簡単にreSTを書けると思います。

*2.Bitbucket Pipelinesはざっくりといえば、リポジトリへのコミットを契機に、環境をデプロイするサービスです。現在、SIOS CoatiではBitbucket PipelinesをオンラインマニュアルをS3にデプロイするために利用しています。

利点

ちょいとわかりづらいと思いますが、この流れに共通している名詞にお気づきでしょうか。はい、ソースコードです。この方式の良い点はreSTの書き方さえ抑えてしまえば、製品コードを書くのと同じ感覚でオンラインマニュアルの作成が行える点です。ちなみに、BitbucketがreSTに対応しているのでマニュアルの大まかな確認はBitbucket上で行えます。オンラインマニュアルの構造など、全体の見た目の部分はS3にデプロイされたhtmlファイルを見れば確認できます。

今後の展望

デプロイ作業は今回の記事で説明している方式によりとても簡単になりました。しかし、マニュアルの中身という点では表記揺れがあったり、冗長な表現があったりと改善したい箇所があります。SIOS Coatiでは文章校正は現在、人力でやっています。できれば、これは人力ではなく、ツールで解消したいところです。文章校正のツールとしては、RedPentextlintがあります。今後はこれらのツールを使って、文章校正の手間を極力軽減して、マニュアル作成を楽しく行える環境にしていきたいと思います。

SNSでもご購読できます。