- 統一された形式 (Markdown) により、断片化が解消されます。
- Gitを基盤 とすることで、バージョン管理、監査、共同作業が可能になります。
- Docsify + GitLab は、重いジェネレーターを使用せずに、軽量かつ迅速なソリューションです。
- Discourseを「サンドボックス」 として使用することは、最終的な公開前にアイデアを共同で洗練するための素晴らしいアイデアです。
問題点: 多くのタスクを抱える状況でのドキュメント作成
日々のタスクの忙しさや、頻繁な緊急対応への切り替えにより、ドキュメント作成のための時間がありませんでした。以下の間で常に切り替わる中で、ドキュメンテーションの書き方を最適化する必要性が指摘されていました。
- CI/CDパイプライン
- モニタリング
- 自動化
- R&D
- 上記のサポート
- 顧客サポート
- 詳細な時間管理
高品質なドキュメント作成に集中する余裕はありませんでした。また、私は手抜きで作業することは得意ではありません。
必要とされていたこと:
- 行動をログに記録する
- 画像、リンク、タイムスタンプを追加したメモを作成する
- 1つのドラフトで複数のトピックを混同しないようにする
- 1台のコンピューターで作業を開始し、別の場所（モバイルデバイスを含む）で続行できるようにする
- ドラフトを自動的に保存し、どのデバイスからでもアクセスできるようにする
- 将来の作業の流れを簡単に復元できるようにする
- 作業のあらゆる段階でドラフトを共有できるようにする。
当初は、ドラフトを完全な作業ドキュメントに変換し、タイムラインの段階に関係なくプロジェクトドキュメントの一部として公開することを目指していました。結果的に見つかったアプローチは、ローカルでの使用にとどまらず、知識基盤全体の事実上の標準となり、プロジェクトで頻繁に使用されるようになりました。
結局のところ、私は柔軟性、拡張性、そして人間中心的なドキュメンテーションシステムを構築しました。これは、高い負荷の下でエンジニアが作業する現実を考慮しています。隔離されたドラフトからオープンな議論への移行は特に重要な決定です。これにより、ドキュメントの品質向上だけでなく、チーム全体がプロセスに関与することが可能になります。
目的: ドキュメンテーションをコードとして扱う
拡張可能な書式設定でドラフトを作成し、ソフトウェアコードと同様にドキュメントを扱います。これにより、いくつかの利点が得られます。
- 書式設定と変換にかかる時間の節約
- オンラインドキュメントの自動生成
- オフラインモード（ブラウザキャッシュのおかげ） (特に重要):
- 顧客の閉域ネットワーク内
- インターネット接続がない場所。
「顧客は、この機能を高く評価しました」と書きたいところですが、ロシアでは役に立つものに対してあまりフィードバックが得られません。形式が普及したかどうかを判断するには、1年間キャッシュされたページを使用し、プロジェクトメンバーが言及している新しい図表やテキストを顧客が見ていないことを理解しようとした顧客からの評価だけで十分です。別のコンピューターでページを開いたとき、インターネットなしでは自分以外には開かないことがわかりました。つまり、ドキュメント作成に費やした時間は無駄ではありませんでした。
選択されたテクノロジーのスタック
Markdown形式を基盤としました。なぜなら、それは：
- GitLab、YouTrack、一部のメッセンジャーでサポートされています
- すべての最新LLMによって正しく認識されます
- Wordのバージョンによる問題、「移動」した画像、互換性のない形式を回避できます。
ドラフトからすぐに以下のものが作成できます。
- オンラインバージョン
- サイトとファイルの両方で同じスタイルを使用した、厳格で美しいPDF。
現在のドキュメント作成の実践
現在、ドキュメントは：
- Markdown形式で書かれています
- GitLabに保存されています:
- ロールベースアクセスにより、すべての従業員が利用できます
- 複数ユーザーによる編集をサポートしています
- 自動的にオンラインバージョンに収集されます:
- Docsifyコンテナを使用します
- 毎分更新されます
- DNS（各プロジェクトの3または4レベルの名前）を通じてインターネット上にサイトが公開されます
- 一貫した外観でPDFとしてエクスポートされます (Vue.jsベース)。
- 図表は2つの形式で作成されます:
- Draw.io (アウトライン、複雑な図用)
- Mermaid (インライン、Markdown内)
- 図の出力：
- SVG（メイン形式）
- 互換性のないプラットフォームの場合、PNG
- 図のソースコードをファイル内に含めます。
ドキュメントの3層モデルとその簡素化
当初は、ドキュメントの3つのレベルを検討していました。
- ドラフト - 個人的で頻繁に変更されるメモ。
- 頻繁に更新されるドキュメント - 共同作業用資料。
- 静的なドキュメント - 最終版、検証済みのバージョン。
ただし、私は次のように決定しました。
- ドラフトの匿名性と隔離を放棄する
- 最初の2つのレベルを結合し、Discourseベースの共通Wikiドラフトにする
- GitLab + Docsifyで静的なドキュメントを残す
2番目と3番目のレベルの間には自動同期はありませんが、このアプローチは実行可能であると考えています。それは知識の流れを簡素化し、同僚にとって参入障壁を下げ、アイデアから公開への移行を加速させます。
ツールと形式
| テキスト | Markdown (.md) | 主な記述形式 |
| 保存 | GitLab | バージョン管理、レビュー、ロールベースアクセス |
| オンライン公開 | Docsify (Dockerコンテナ内) | Gitからサイトを自動的に構築 |
| ドラフトとディスカッション | Discourse | アイデアの共同検討 |
| 埋め込み図表 | Mermaid | Markdown内のブロック図、シーケンス図 |
| 外部図表 | Draw.io (.drawio → .svg) | 複雑なアーキテクチャ図 |
| PDFエクスポート | Docsify + 統一されたVueスタイル | オフラインアクセスと顧客への配布用 |
その他のこと
このスキームには、まだ改善すべき点があります。
- Discourse と GitLab の同期
- レビュープロセスを改善し、最終版の公開準備段階に移行する
- リンクの一貫性を維持する
- 公開を自動化する
- 不一致が見つかった場合のフィードバックメカニズムと修正に関する通知