ドキュメント執筆にもGit、ビルド、テストで再利用性や整合性を実現する「Writerside」、JetBrainsがプレビューリリース

今回は「ドキュメント執筆にもGit、ビルド、テストで再利用性や整合性を実現する「Writerside」、JetBrainsがプレビューリリース」についてご紹介します。

関連ワード （作成、単一、表現可能等） についても参考にしながら、ぜひ本記事について議論していってくださいね。

本記事は、Publickey様で掲載されている内容を参考にしておりますので、より詳しく内容を知りたい方は、ページ下の元記事リンクより参照ください。

Kotlinなどの開発元として知られるJetBrainsは、テクニカルドキュメントのための一連のツールを統合したドキュメントオーサリングツール「Writerside」のプレビューリリースを発表しました。

ソフトウェア開発においては、テキストで記述されたソースコードをGitでバージョン管理し、ビルドによって複数のソースコードを1つのアプリケーションへとまとめ上げ、コンパイルし、テストをして本番環境へのデプロイによりアプリケーションを公開します。

そしてこのプロセス全体を、さまざまな機能を備えたツールチェンを用いて自動化することで、ソフトウェア開発の効率を高めています。

一方で、例えばアプリケーションのチュートリアル、SDKやAPIのリファレンスドキュメントなどのドキュメントの制作過程においては、複数のファイルをフォルダにまとめ、手作業で目次のページとリンクさせることや、ソースコードのサンプルの記述や、警告のための赤いアイコンなど、リッチな表現の実装のためにCSSやJavaScriptなどを手作業でドキュメントファイルの中に書き込んで実現してしまうケースも多いでしょう。

この方法では、目次が変わるたびに慎重な変更作業が必要ですし、見栄えを改善しようとしても1つ1つの該当ページをマニュアルで書き換えていくほかありません。

こうした手作業の多いドキュメントの作成を、ソフトウェア開発者が用いているのと同じようにツールチェーンによる自動化によって効率を高め、開発者とのコミュニケーションを容易にする目的を持っているのが、今回プレビューリリースとなった「Writerside」です。

Markdownに対応、MermaidやLaTexの記述も可能

Writersideでは、ファイルだけでなくGitによるコンテンツの管理が可能。コンテンツの再利用も容易になっています。

ドキュメントはMarkdownもしくはJetBrainsの独自セマンティックによるXML形式での記述が可能です。また、Mermaidによるダイアグラムの記述、LaTexによる数式の記述も可能になっています。

テンプレート機能によって、リファレンスマニュアルなどでよく見られる「ワーニング」の赤い文字や「Note」などの注釈のレイアウトなどが、簡単なマークアップで表現可能になり、あとからまとめて見栄えなどを変更することも可能です。

ビルドを実行しなくとも、Writerside上で単一のページをライブプレビューしたり、Webブラウザーでサイト全体を開いて参照できたりできます。

ライブプレビューとビルドではテストが行われ、マークアップの属性やセマンティックなどの誤り、あるいは組織毎に設定された執筆ルールなどから外れた要素があれば検出できます。

実際にJetBrainsのIntelliJ IDEAドキュメントやKotlinヘルプなどは、Writesideで作成されているとのことです。