- Ruby / Rails以外の開発一般
- 勉強会
READ MORE
こんにちは、hachi8833です。
今回は、弊社の社内ドキュメントリポジトリとして導入を検討した以下のサービス/アプリケーションの比較とその結果をお送りします。リストは順不同です。
弊社では従来、PukiWiki(バージョン 1.4.7)を長年社内のドキュメント保存場所として利用してきましたが、次のような問題が生じていました。
好みの問題もあるかと思いますが、PukiWikiのマークアップ記法は今となっては後述のMarkdownと比べて決して使いやすいとは言えません。
例 | PukiWiki記法 | Markdown記法 |
---|---|---|
リンク | [[文字列:http://~]] |
[リンク名](URL) |
見出し | *** h3 |
###␣h3 |
番号なしリスト | -リスト --リスト |
-␣リスト ␣␣- リスト ( + や* でもよい) |
強調 | ''強調'' (一重引用符2つ) |
**強調** |
斜体 | '''強調''' (一重引用符3つ) |
*強調* |
注: “␣”はスペースを意味します。
特にPukiWikiを書く頻度が下がると、更新のたびに書き方をググって思い出すこともしばしばです。
PukiWikiを含む従来のWikiではドキュメントを比較的自由に構成できるので、ともすると長大な目次、長大な本文ができあがってしまいます。こうなってしまうと後から分割するのも面倒ですし、本文以外に目次もメンテナンスしなければいけません。
PukiWikiを含む従来のWiki記法(残念ながらWikipediaのMediaWiki記法も含め)は、なまじレイアウトをある程度コントロールできるために記法が複雑になり、気をつけて書かないとレイアウトが崩れることがあります。
GitHubやGitLabで標準採用されたこともあり、近年はMarkdown記法が急速に定着しつつあります。
Rails開発者も、rails new
した後真っ先にREADME.rdocをREADME.mdに変更することが普通になりつつあります。
Markdownの最もありがたい点は「レイアウトを意識しなくてよい」ところだと思います。
Markdownはドキュメント作成に特化して記法を大胆に絞り込んだことで、ずっと覚えやすくなっています。そしてレイアウトについてはMarkdownでは原則扱わず、CSSやHTMLタグの直接記述に任せるという潔さが成功の一因だったと感じています。
Markdown記法で属性を扱うのはあまり簡単ではありませんが、無理して属性を追加するより、属性を追加しなくて済むようCSSや運用でカバーするのがよいと思います。
以上のような理由から、PukiWikiの後継となるドキュメントリポジトリ・コラボレーションサービスを検討しました。
BPSのエンジニアであればGitLabでのMarkdown記法が定着しているので、新しい記法を覚えずに済むのは大きなメリットです。PukiWikiは登場してから長いので、PukiWiki記法を知らない人も増えています。
こうした要件は組織によって異なりますが、BPSの場合はドキュメントの生産性向上や、検索/共有などの円滑化といった「目に見える」効果を期待しています。料金も重要な要素です。
BPSの場合、通常業務になるべく負荷をかけずに導入できるサービス/アプリが求められます。
当然ながら、データ喪失回避のためのサポートは重要です。また、今後サービスを移行することになった場合のインポート/エクスポートも保険のために必要です。
(更新しました) ドキュメントの公開範囲をある程度自由にコントロールできる機能が求められます。案件にかかわっていないメンバーに見せないようにする機能や、有料ユーザー以外のユーザーに一時的に共有する機能は欲しいところです。
以上の条件を念頭に、PukiWiki後継となるドキュメントコラボレーションサービス/アプリケーションを比較してみました。限られた時間の中での検討なので、すべての条件を検討したわけではないことをお断りしておきます。
また、価格については変動が予想されるためリンクのみ示しました。
Markdownの支援機能(自動補完など)や、Slackなどのチャットアプリとの連携やAPI機能はどのサービス/アプリにも備わっていました。
Qiitaサービスをコラボレーション用に拡張した有料サービスです。
esa LLCが提供するドキュメントコラボレーションサービスです。
Atlassianが提供する総合的なチーム向けドキュメントサービスです。
株式会社クレイが運営するドキュメントコラボレーションサービスです。
旧: 株式会社クロコス(現在はヤフー株式会社に合併)で開発されたWikiです。
Qiita:Team | esa.io | Confluence | DocBase | Crowi | |
---|---|---|---|---|---|
1. Markdown | ○ | ○ | △ | ○ | ○ |
2. 投資対効果 | ○ | ○ | ○ | ○ | △ |
3. 導入・運用 | △ | ○ | △ | ○ | △ |
4. バックアップ・保全 | ○ | ○ | ○ | ○ | △ |
5. アクセス制御 | △ | △ | ○ | ○ | △ |
検討の結果、BPS社内の一部チーム限定でDocBaseをしばらく使ってみることにしました。選定のポイントは以下でした。
esa.ioとどちらを選ぶかで最後まで迷いましたが、グループ限定の公開機能の有無が分かれ目となりました。DocBaseには残念ながらスライド機能はまだありませんが、今後のアップデートに期待したいと思います。
Confluenceは社内に経験者がいるのと、高機能かつ価格的にも魅力的だったのですが、準備と導入教育を十分に行わないと機能を活かしきれないことから、今回は見送りました。
弊社の場合、既にSlackの導入が成功を収めているので、Slackによるリアルタイムコミュニケーションと、GitLabやRedMineなどによるプロジェクトごとのドキュメントの中間に位置するような静的なドキュメントの管理・共同編集が行えるプラットフォームを求めていましたが、DocBaseを含め、今回検討したサービス/アプリはその点についてはおおむね条件を満たすことができたと思います。
今回検討したサービス/アプリには、Googleドキュメントのような文字単位のコメント・レビュー機能を備えたものはありませんでした。
ドキュメント単位のコメントだと細かな点を指摘しにくく、指摘された場所を探すのが面倒になりがちです。
Googleドキュメントのコメント・レビュー機能はドキュメントに直接記入でき、自動的にメールが送信されてすぐ確認でき、承認してすぐ反映できるのが大きなメリットです。
また、ドキュメントに直接コメントする方法なら、「何行目のxxは〜だと思います」といった記述なしで修正内容を直接記述できるのも無視できません。ちょっとしたことのようですが、Slackのおかげでメールタイトルみたいなものを入力しなくてよくなったように、修正内容だけを入力しても大丈夫なつくりになっていると、利便性が大きく向上すると思います。
個別にユーザー管理しなければならない社内サービスが増えると、地味に負担になります。
Active DirectoryやLDAP連携といった方法も考えられますが、昨今であればGoogleアカウント(G Suite)ベースでユーザーを管理できると助かります。
G Suiteベースなら画像やドキュメントもGoogleドライブに配置することもできそうですが、URLを指定して画像や添付ファイルをページに埋め込むにはGoogleドライブ側で「リンクを指定して共有」(リンクを知っていれば誰でも見えてしまう)にしないといけないという問題が立ちはだかっています。これについてはGoogleドライブのフォルダアクセス権を反映してURLを限定共有できるよう、まずGoogle側で対応してもらう必要がありそうですね。
今後、こうした点が改良されたMarkdownベースのソリューションが出現すればまた移行するかもしれません。
現在は社内の1チーム内で限定的に運用中ですが、ドキュメントが毎日のようにモリモリと作成・更新されています。やっぱりMarkdownで書けるのはうれしいです。
さらに追伸: 現在は社内標準となりました。