世の中Markdownライク¹にかけるドキュメントサービスはたくさんあります²。さて私もいろんなサービスでドキュメントを書いてきたのですが、その中でもBacklog Wikiは機能が貧弱で書き心地が決してよくありませんでした。そんな折、2024年9月にリアルタイム同時編集ができる「ドキュメント機能」がアナウンスされました。

先日、Wikiに書いていたマークダウンをドキュメントに移行して、ドキュメント機能の現状を考える機会があったので、その使い勝手と課題をメモします。

はじめに

ドキュメント機能は、2025年3月現在でもβ版です。つまり使い勝手の悪さを感じてもまだβ版なので改良される余地はありそうです。本記事では、他のマークダウンサービスの経験を持ったうえで、ドキュメント機能を実際に使うことを念頭においています。

Wiki機能とドキュメント機能の大きな違い

ざくっと違いだけをまとめると以下の通りです。細かい点は置いて、まずは違いだけまとめます。

リアルタイム同時編集

リリース文のタイトルに入れているあたりウリにしたいと予想できます。実際Wiki機能は誰かが書いているときに他人が保存すると記事の編集が競合するため、現代のドキュメントサービスとしては使い勝手が極めて悪かったポイントです。

WSIWYGスタイル

NotionやConfluenceをイメージしてください。マークダウン的な入力するとマークダウンは表示されず、スタイルが反映された状態で表示されます。UX的にはConfluenceのツールバーとNotinoのスラッシュコマンドの両方を取り込んでいる感じです。Wiki機能のマークダウンをドキュメント機能で貼り付ければそのまま表示される感じです。

スラッシュコマンド

Notionやesaなど多くのサービスでもあるもので、ツールバーにいかなくても/を入力すると同様の呼び出しができる機能です。リスト的にはNotionに近いです。

コメント

ConfluenceやNotion、esaにあるのと同様で、記事に対してコメントを残すことができます。コメントは記事の下に表示されます。ただ、どのサービスもこれを活用しているシーンはそこまで見かけない気がします。

目次が記事の横に表示

地味ですがやっと改善されました。Wiki機能の目次は、なんとタグ一覧やページ一覧の下に表示される使い勝手の悪さでした。このため、目次を本文頭に表示するたには本文で[toc]と入力するのが定番でした。³

コードブロックのハイライト対応

例えばGoのコードはWiki機能でハイライト対象外でしたが、ドキュメント機能では対応されています。地味にうれしい。

Mermaid図は描画される

今のドキュメントサービスでは標準的に求められているぐらいにはデファクトになりましたね。Wiki機能では描画されませんでしたが、ドキュメント機能では描画されるようになりました。これで描画された結果をスクリーンショットとって記事に挿入する不毛さから解放されます。

表示サンプルに使うマークダウン

以降は昨日の違いを試すためのサンプルマークダウンです。これを用いて、Wiki機能とドキュメント機能でマークダウン解釈がどう違うのか確認します。こういう新しいドキュメントサービスを出すときはどのようなルックアンドフィールの違いがあるか、サンプルを提示してくれると印象いいんですよね。⁴

Test markdown output with common format | Gist

2550×1440モニターで拡大率90％の見た目は次の通りです。わかりやすい違いを見ていきましょう。目次が右から左に移動されています。スタイルが大きく変わり、縦に長く、見出しレベルにかかわらず下線が入らなくなり、テーブルで項目がないときの表示が歯抜けではなくなりました。チェックボックスやMermaid、コードハイライト言語の違いあります。

Wiki機能	ドキュメント機能

Wikiからドキュメントに文書を移した所感

100以上のWiki記事をドキュメント機能へ移行した際にメモしたことをまとめます。β版なので色々気になる挙動があっても別によいでしょう。ただ、🐛🐞項目はβ版とはいえ、まずい事故を誘発する状況なので早めに直ってほしいです。

📝: 機能としてのメモ項目
👍: Wiki機能に対してよいと感じた項目
🙅: 触った感触が微妙な項目
🐛: バグっぽい挙動
🐛🐞: 事故を誘発するようなバグっぽい挙動

📝APIやSDKがまだない

ドキュメント機能はAPIやSDKがまだないです。公式TypeScript SDKもドキュメントAPIはありません。(最終更新7か月前)

APIやSDKがあると、大量の記事があってもどうとでもなるので欲しかったところです。今回はなんと手で記事を移行しました。力技、なので癖のある挙動をこうやってメモしていたわけです。

📝使い方ドキュメントはある

ドキュメントの基本的な使い方 | Backlog ヘルプセンターがあります。

ただ、本記事に紹介するような機能の違いやWiki機能との使い勝手の違いは書かれていません。使いたくなるように細かい動作や制約やアップデート状況、リリース目安など丁寧な姿勢を示してもらえると、ユーザーとしても期待を持てるのですが。

📝ドキュメントのURLは階層にかかわらず固定

記事は常にパーマリンクです。意外と記事タイトルとか階層に依存するサービスがあるんですよね。そう、Wiki機能の記事です。保存した記事自体はパーマリンクですが、編集中はwiki/プロジェクト略称/記事タイトル/editというURLです。

📝ドキュメントのコンテンツをコピーしてもマークダウンにはならない

ドキュメントの内容をコピーしても、マークダウンとして保持されていません。マークダウンとして取得するには、エキスポート > Markdownを選ぶとクリップボードやファイルにマークダウン出力できます。

📝Wikiにアタッチした画像はドキュメントで参照できない

改めてアップロードする必要があります。幸いWiki機能の記事からドラッグ&ドロップで画像をアップロードできるので、同じ記事を2窓開いておいて画像をアップロードすると手早いです。APIはよ、APIファーストで頼む。

📝見出しでコードブロックを使うとフォントが縦長になる

動作に影響はないがかっこ悪いフォントに感じるのは個人差かな。

📝1つのドキュメントに添付できるファイル数に上限がある

ドキュメントで画像などを多用するページは、添付ファイル数上限に注意です。ドキュメントで1ページの添付ファイル数に上限があると、使い方に直接影響でる面倒な制約なのであまり印象よくないですね。

Wiki機能もファイル数に制約があるので同様と予想しています。

📝テーブル構文の解釈変更

ドキュメント機能でテーブルを書く分にはスラッシュコマンドやツールバーを使うでしょうから、特に問題なさそうです。ただ、Wiki機能からコピー&ペーストすると、テーブル構文の解釈が変わっているので注意が必要です。

より厳密な解釈になったので、妙な書き方が書けなくなったのは良いことだと受け止めています。

テーブル構文のタイトルが必須になった

以下のような「タイトルなしのテーブル」を貼り付けた時の挙動が変わりました。

| --- | --- |
| foo | bar |
| piyo | poyo |

ドキュメントでは描画されず、タイトルが必須になりました。

Wiki機能ではタイトル省略でも描画されていました。

区切り線の数の厳密化

以下のような「区切り線の数が一致しないテーブル」を貼り付けた時の挙動が変わりました。

区切りが多い

| タイトル | たいとる |
| --- | --- | --- |
| foo | bar |
| piyo | poyo |

区切りが少ない

| タイトル | たいとる |
| --- |
| foo | bar |
| piyo | poyo |

ドキュメントでは描画されず、区切り線の数は厳密に一致する必要があります。

Wiki機能では区切り線が不一致でも描画されていました。

👍Wikiからの移行はマークダウンコピー&ペーストで行ける

ドキュメントはWYSIWYGスタイルでMarkdownが見えない (MediumやNotionと同じ) だが、マークダウン貼り付けで自動的に見た目は調整されます。このため、基本的にマークダウンコピー&ペーストで行けます。

👍リアルタイム編集できる

リリース情報から最大12名のようです。リアルタイムで同時編集できてようやく現代的なチームドキュメント体験が。

同時書き込みを行っていると、画面更新が若干ラグいと感じます。

👍コードブロックの言語対応が増えた

デフォルトはautoで自動検出ですが、これまで対応していなかった言語もハイライトできるようになりました。Goもハイライトされてるのはうれしいですね。

👍常にサイドバーの見やすい位置に目次がある

ドキュメント機能ではページの右上に常に目次が表示されています。また本文に目次出す[toc]キーワードは機能しないようです。

折りたたんでマウスホバーで表示という挙動もできます。

Wiki機能はタグ一覧やページ一覧の下に目次があって、まともに機能していなかったのが解消されます。

👍パスはタイトルから独立した

ドキュメント機能の記事タイトルはパスに影響しません。また、これに伴い記事タイトルで/を使えるようになりました。もうCI/CDをCICDと書かなくていいです。

Wiki機能では記事タイトルに/をいれてツリー構造を作る必要がありました。タイトルがパス構造を示しパス構造の区切り文字が/だったため、ページ名に/を含められませんでした。(例: CI/CDではなくCICDとするしかなかった)また、記事タイトルがパス構造を担うということは、同一ツリー配下にしたい記事すべてでパスをそろえる必要があります。Fooツリー配下に10記事あったとして、FooからBarにリネームしたいときは10記事すべてのタイトルを修正するわけです。つらい。

👍ドキュメントの並び順は新着+自分で並び替え

ドキュメント機能の並び順は登録順 (更新順ではない)です。ドラッグ&ドロップで明示的に並び順を調整できます。パスとタイトルが独立し、ドキュメントの並び替えをマウス操作でできるようになった結果、ずいぶん楽になりました。

Wiki機能では名前abc順で自動整列だったため、Wikiの並び順はタイトルで調整するしかありませんでした。

👍階層のフォルダを消すと子ドキュメントは消える

ドキュメント機能は、親階層を消すと子階層は道連れで消えます。以下では、fooを消すと配下のbar記事も消えます。ゴミ爆からの復元で親階層ごと復元すれば、TOP階層に階層を保って記事が復元されます。

Wiki機能では記事毎に共通のプレフィックスでツリー構造を表現していたため、全記事を消す必要がありました。

👍検索結果はWikiとドキュメントは独立

検索してもWiki機能の記事がまじってカオスというのは避けられます。

Backlogは検索が弱すぎる

なお、Backlogを使ってて最もつらいのは検索ですが、検索自体は何も向上していません⁵。検索は以下の理由から機能不全です。

検索しても記事のタイトルしか表示されないので、どのタイトルのどのコンテンツでヒットしたか開くまでわからず判断が難しい
特定階層を除外など検索オプションが皆無で、記事が多いほど検索して記事にたどりつけなくなる

このため議事録や日報管理にドキュメント機能を使うと、文字列で検索しても本当にほしかったドキュメントより日報や議事録が大量にヒットすることが日常茶飯事です。Wiki機能でこの経験をしている人は多いでしょうが、このまま検索が改善されなければドキュメント機能でも同じことになります。アナウンス記事で定例議事録を例に出しているのですが、検索で困ってないのか?と、衝撃でした。

👍URL貼り付けでページ名に変換される

別ドキュメントのURLを貼り付けて「メンション」を選ぶとページ名に切り替わり、ページ名変更にも追随します。これはNotionやesaの挙動と同じですね。

Wiki機能は[[記事パス/タイトル]]のように簡略表記でリンク書くことができるのですが、ページパスやタイトル変更でリンクが壊れていました。代わりに記事のパーマリンク[タイトル](https://xxxx.backlog.jp/alias/wiki/xxxxx)を使えばタイトルに依存しないのですが手間がかかっていました。現代的体験!

👍マークダウンスタイルでチェックボックスが使えるようになる

マークダウンの* [ ]や- [ ]でチェックボックスが作れるようになりました。GitHubとかで多用している人も多いのではないでしょうか。

Wiki機能では対応できてなかったのがついに。

👍Mermaidが描画できるようになった

ドキュメントはMermaidをそのまま描画できるのでスクショを使わなくてよくなります。Mermaidバージョンはv11.4.1で、2025年2月時点で最新版が入っています。

Wiki機能では描画されずスクショという不毛な作業が必要でした。

👍添付ファイルが本文で参照されているかわかるようになった

ドキュメント機能では、ドキュメント本文で参照されていない添付ファイルが明示されるようになりました。これにより添付画像を消すとき安全になりました。

Wiki機能では添付ファイルが本文で利用されているかわからなかっため、本文で使われていない添付ファイルを消すには、「添付ファイルのリンクを取得、本文を編集で開く、本文にリンクがないかチェック」と3ステップ必要でした。かなり楽になりましたね。

🙅見出しレベルにかかわらず下線が入らない

ドキュメント機能では見出しレベルがいくつでも下線は入りません。見出しレベルにかかわらず下線が入らないのは見出しの区別がつきにくくて個人的には好みじゃないです。見出しレベルによって下線の太さを変えるなどの工夫があるとよいですね。

Wiki機能では見出しに下線が入っていたことから違和感になっています。ただ、ドキュメント機能はスタイルがちょいちょい変わっているので仕様の可能性もあります。

🙅子ページは親に自動追加されない

Confluence、Notionやesaでは、子ページを追加すると親ページに自動追加させることができます。似たUIのドキュメント機能でもそれを期待しましたが、できませんでした。残念です。

この機能は本当に便利で、親ページで子ページの簡易まとめやレイアウトを組めるんですよね。Notionの例を見るとわかるのですが、親に子ページリンクが自動追加されるので、あとは親ページで好きにレイアウトすればよくなります。なおConfluenceの場合は、表示する階層を選べるのでより目次に近い使い方ができます。

以下はNotionで、子ページを追加すると親ページにリンクが自動追加されている例です。

サイドバー > ページのツリー構造

親ページの編集画面

🙅記事移動時のマウスドラッグが繊細

サイドバーで記事の順番をマウスドラッグで移動するとき2つ難点があります。

ツリー構造の記事上をホバーしたり微調整中に1s前後触っているとツリーが展開される
記事をドラッグするときツリー配下とツリーの外の境界が狭いため、誤ってツリーの外に置いたり、誤ってツリーの中に置いたりしやすい

ドラッグ終了とツリー展開のタイミングが重なると、記事がツリーに入ってしまって、しょんぼりします。他サービスもドラッグで重なるとツリー展開されるのは同様ですがあまりつらくないあたり、ツリー展開の反応時間を遅くするなど体験改善ができそうですね。

ドラッグのワークアラウンド

ドラッグ時にツリーの上ではなく外側を通るようにすると、ツリーが勝手に展開されるのは防げます。

ドラッグ時にツリーと重なっているので、不意にツリーが展開してつらい

ドラッグ時にツリーと重なってないので、ツリーが展開しない

🙅新規ドキュメントを+で追加する位置が選べない

地味に不便なのですが、新規ドキュメントを追加する位置が選べず、現階層の一番上に追加されます。この挙動は記事移動時のマウスドラッグが繊細と組み合わさって、記事追加後のストレスです。

Wiki機能の記事と同じ順序に手動で移行しようと思ったので、「Wiki側で階層一番下の記事」から順番にドキュメントへ追加していくことでドキュメントの並び替え不要にしていました。こういう回避をしないと毎度並び替えが必要になりストレス度高めです。

🙅番号付きリストがレベル変わっても1.のまま

番号付きリストのレベルが変わっても表記は1. -> 1. -> 1.のままです。ただこの挙動はWiki機能も同様なので仕様っぽいですね。

ドキュメントサービスの多くは、レベルごとに1 -> i -> aと表記が変わり便利なのでちょっと残念です。

マークダウンのライブラリ挙動依存かな。

🐛マークダウン貼り付け挙動が変

Wiki機能の編集で表示されるマークダウンをコピーしてドキュメント機能に貼り付けると期待通りスタイルされます。しかしVS Codeのマークダウンをそのまま貼り付けるとコードブロックになります。メモ帳に貼り付けて、それをコピー&ペーストすると問題ないので書体を持っているかどうかがトリガーのようです。

ワークアラウンド

書体を持たないエディタやWikiページを経由してコピー&ペーストしましょう。

🐛base64を含んだ文字列はペーストできません (修正済み)

2025/3/3追記

Nulab社にフィードバックしたところ修正連絡がありました。base64文字列をペーストできるようになりました。ありがとうございます。

**追記ここまで

base64という文字列が入っているとダメです。base64エンコードされた文字列じゃなくて、base64という文字列がだめ。意味が分からないのでバグとしか思えないです。

ワークアラウンド

BASE64やBase64と大文字混ぜればokです。

🐛画像をドラッグ&ドロップで挿入時のカーソル位置が変

画像のドラッグドロップの位置判定を「ドキュメントで画像をドラッグした位置」ではなく「ドキュメントで最後にクリックした位置」で行っているようです。これは、ドラッグ&ドロップの挙動としては不自然なので、画像のドラッグで示した行にしてほしいです。バグですよね?

再現手順です。

マークダウンをコピー&ペースト
ドキュメントのどこもクリックしない
Wikiの画像をドキュメントの適当な行にドラッグ&ドロップ

画像がドキュメントの末尾に挿入される

ワークアラウンド

画像のドラッグ&ドロップ前に、挿入したい行をクリックします。これで画像を意図した行に挿入できます。

🐛番号付きリストと箇条書きリスト混在がドキュメント機能で書けない

ドキュメント機能で書いていて、番号付きリスト中の要素を箇条書きリストにできないようです。このため以下のような書き方はドキュメント機能ではできません。

1. foobar
    * okonomi
2. bazpiyo
    * takoyaki

ワークアラウンド

マークダウンのコピー&ペーストだと作ることができるます。ライブラリ的には対応しているものの、エディター部分で制約を受けているようなので、バグと仕様どちらか微妙なラインですね。

🐛🐞保存せずページ遷移しても保存される

ドキュメント機能のページ編集中は右上に「保存して終了」が表示されています。しかし、保存せずにページ遷移しても保存されます。編集したけどやっぱりやめたという経験は誰もがあるでしょうが、一度編集するとページを閉じても保存さるということです。

これは初めて見る挙動、本当にこの挙動なのか数回動作確認してしまいました。

ワークアラウンド

ページ遷移する前に「元に戻すボタン」で変更する前に戻してからページ遷移しましょう。ちなみに元に戻すボタンは、「これ以上戻れなくてもボタンがグレーアウトされない」ので、いつまで戻せばいいかはどうやって判断するかは賭け要素があります。なお、一度ページ遷移すると元に戻すは使えません。

保存デザインはどうあればいいのか

こういう動作経験は自分でドキュメントサービス作っているときぐらいしか遭遇しないので、改めて保存デザインについて考えてみます。同時編集できるサービスの代表といえるGoogle DocsやNotionは「問答無用で上書きされ保存動作という概念がない」ので、保存ボタンがないデザインは納得できます。⁶しかし、Backlogドキュメント機能は「ページを開いた時は読み取りのみ」「編集したいときは編集ボタンを押す」というUXデザインで、編集時だけ「保存して終了」ボタンをおいています。ユーザーはUIで挙動を予想するので、保存して終了を押さないと保存されないことを期待するでしょう。保存せずにページ遷移しても保存されるなら保存ボタンの意味ないですし、ボタンを置いているのは誤解を招いていると感じます。仮に今のデザインのまま修正する場合、保存しないでページ遷移しようとしたら保存するかダイアログ確認を入れれば、不意のユーザー操作事故は防げそうです。

Notionは保存がない代わりにいきなり編集して書き換わるのを防ぐロック機能があります。Backlogドキュメント機能には記事のロックがないことから、Notionのようなシームレスな書き込み体験は志向していないように感じますが果たしてどうなんでしょう。⁷

まとめ

今のところβ版という感じですが、機能自体はWiki機能よりだいぶんよいです。Wiki機能と同じ感覚で使うと、変更して保存前にページ閉じても意図せず保存された、となる可能性があるのでそこだけ注意したほうがいいです。

Slackでちまちまメモしていたので一瞬でかけると思ったら、丁寧に挙動追いかけていたら時間が無限にかかりました。base64の不具合報告したらサクッと直してもらえたので、一通りフィードバックしておきました。

参考

Markdownライクとしたのは、マークダウンでかけるだとWSIWYGなものが省かれてしまうため↩
チームで使うものとしてはNotion、esa、Confluence、Consense、Qiita:Team、Dropbox Paper、Azure DevOpsのWiki、BacklogのWikiあたりが開発文脈でよく見かけます。↩
はてなブログの[:contents]をイメージしてください。↩
こういうサービスの表示の違いは生成AIのチャットUIではできないので、サービス側がサンプルを提示して手触りに気を使っていることを示すの大事派です。↩
リアルタイム編集よりこっちのほうが致命的な弱点だと考えています。Wikiとして検索が機能しないのは書いてもたどりつけないので価値を誰も活用できません。ドキュメントでリアルタイム編集できても、後から見つけられない記事になんの意味がありますかね?↩
代わりに変更履歴のバージョニングがちゃんと機能しているので問題ない↩
同時書き込み時は保存させたい、みたいな仕様と競合してるのかしら↩