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

2023年10月26日

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

fig

ソフトウェア開発においては、テキストで記述されたソースコードを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で作成されているとのことです。

あわせて読みたい

開発ツール JetBrains




タグクラウド

クラウド
AWS / Azure / Google Cloud
クラウドネイティブ / サーバレス
クラウドのシェア / クラウドの障害

コンテナ型仮想化

プログラミング言語
JavaScript / Java / .NET
WebAssembly / Web標準
開発ツール / テスト・品質

アジャイル開発 / スクラム / DevOps

データベース / 機械学習・AI
RDB / NoSQL

ネットワーク / セキュリティ
HTTP / QUIC

OS / Windows / Linux / 仮想化
サーバ / ストレージ / ハードウェア

ITエンジニアの給与・年収 / 働き方

殿堂入り / おもしろ / 編集後記

全てのタグを見る

Blogger in Chief

photo of jniino

Junichi Niino(jniino)
IT系の雑誌編集者、オンラインメディア発行人を経て独立。2009年にPublickeyを開始しました。
詳しいプロフィール

Publickeyの新着情報をチェックしませんか?
Twitterで : @Publickey
Facebookで : Publickeyのページ
RSSリーダーで : Feed

最新記事10本