※ 画像の説明：若い男性がコードを埋め込んだ多数の画面に囲まれたテーブルの前で座っており、コンピュータから煙の柱が立ち上っています。
- Markdown の単一形式は離散化を防止します。
- Git が基盤 であるため、バージョン管理、アウトカバー、コラボレーションを実現します。
- Docsify + GitLab は重たい生成器よりも軽快です。
- Discourse が「砂場」 としては素晴らしいアイデアです – まとめたアイデアの集大成に向けて共同で調整します。
書き方の問題：多作業環境でのドキュメンテーション
日常的な作業や、「火事」という切り替えが頻繁に起こるため、ドキュメンテーションを書く時間は残りませんでした。ドキュメントの作成については以下のような混乱の中で議論されていました:
- CI/CD パイプライン
- モニタリング
- 自動化
- R&D
- 前述の作業への支援
- 顧客支援
- 時間帯別の詳細記録
集中して質の高いドキュメントを書く余裕はなかったものです。また、「手抜き」すること自体が私にはできませんでした。
求められた点は以下の通りでした:
- 行動ログを残す
- ポートフォリオに写真・リンク・時刻マーカーを付加する
- 同一のドキュメント内に異なるテーマを混ぜない
- 1台のコンピュータからでも次に別の端末（そしてモバイル）で続けられる
- チャプターは自動的に保存され、どこからでもアクセスできるようにする
- 進行履歴を後で簡単に確認できる
- 中間段階のチャネルで共有可能
最初は「原稿が完成したらプロジェクトドキュメント内に公開し、タイムラインとは無関係」にすることが目的でした。結果として、それ以上の利用範囲を超えて共有される知識のインテグレーションへと変わりました。
結論：高負荷下のエンジニアライフに合わせた、柔軟でスケールableで人間指向のドキュメンテーションシステムを構築しました。孤立した原稿からの開発・共同プロセスへの転換は特に重要な決断でした。その結果、ドキュメントが適正レベルまで高められるだけでなく、チーム全員がプロセスに参加しやすくなりました。
ドキュメンテーションの「コード」としての理念
原稿をソースコードと同様に扱うことでいくつかの利点が得られます:
- 形式化や変換にかける時間が短縮される
- オンラインドキュメンテーションが自動生成される
- ビジネスモデル（オフラインモード、ブラウザキャッシュ）を備える
ビジネスの顧客からは高評価されました」 と書きたいところでも、ロシアでは有用なことには声を上げにくいです。実際に1年間キャッシュページを閲覧し、プロジェクトに関する新しいテクニックや文言を理解できた顧客がいました。そして別のコンピュータからページを開けば、外部で他の誰も閲覧できなかったことが分かり、ドキュメント作成に時間を割いてよかったと感じる証拠です。
選択された技術スタック
ベースになっているのは Markdown であり、理由は以下の通りです:
- GitLab、YouTrack、一部のメッセンジャーでもサポートされています
- すべての最新 LLMs (人工知能) が正しく解釈できます
- Word のバージョンズや画像の破損や互換性問題を回避します
原稿はすぐに以下の形で取得できます:
- オンライン版（Docsify）
- 厳格かつ美しい PDF フォーマット（同一デザインのもの）
現在実施されているドキュメンテーションPRACTICE
現在のドキュメンテーションは以下のように構築されています:
-
Markdown (md) で書かれた
-
GitLab 上に保存され、ロールベースでアクセス可能
-
モジュール別に Docsify が自動的に集積し、更新は1分ごと
-
インターネット上にサイトを公開し、DNS (3・4レベル名) で公開しています
-
PDF 版（Vue.js 基調の同一デザイン）が自動的に生成されます
-
図表 は Draw.io (ウィンドアイランド) で、複雑なシンボルを作成し、Mermaid (inline ブロックスコード) でマークダウン内に挿入
-
図形の出力:
- SVG（主フォーマット）
- PNG（互換性が低いプラットフォーム用）
- それぞれのコードブロックも添付されています
ドキュメンテーションの３段階モデルとその簡略化
初期に3段階を検討していました:
- 原稿：個人向け、変更頻度が高いノート
- 定期的に更新されるドキュメント：チーム共有ワーク
- 静的ドキュメント：検証済みの最終版
しかし以下のような方針にしました:
- 個人・非公開の原稿は廃止
- 1と2を共同Wikiベースの Discourse で統合
- 3は GitLab + Docsify へ
自動的な2と3レベル間の同期は行っていませんが、この方式は知譎の流れを整える効果があり、コミュニティへの入口を低く抑え、アイデアから公開までを迅速化します。
インストール・フォーマット
|—|—|—|
|テキスト形式|Markdown (.md)|書き方の主な形式 |
|保存|Slack (GitLab)|バージョン管理、レビュー、ロールベースアクセス |
|オンライン公開|Docsify (Docker コンテナ)|Gitから自動生成のサイト, 1分毎に更新|
|原稿・ディスカッション|Discourse|共同でアイデアを練る場 |
|内部図面(マークダウン内)|Mermaid|マークダウン直接に埋め込む|
|外部図面(draw.io → .svg)|Draw.io (.drawio から .svg)|複雑なアーキテクチャシンボル作成 |
|PDF 出力|Docsify + 一貫した Vue.js テーマ|オフライン利用と顧客共有用に生成]
もう少し改善する余地があります
- Discourse と GitLab の同期を実装
- レビューと公開準備のプロセスを最適化
- 参照対応整備
- 自動公開機構
- 検証された不一致や変更に対する通知メカニズム