重い前提条件
ドキュメントの書く最適化という問いは、タスクの遂行に追われる忙しさの中で生まれました。パイプラインの切り替え、モニタリング、自動化、RnD、サポート、時間の詳細記録など、頻繁な切り替えがドキュメンテーションに集中する余裕を奪っていました。
行動ログを取る
私は自分の行動をログに記録し、画像やリンク、タイムスタンプでテキストを補足する必要がありました。同じ下書き内でテーマが重複しないように、その後簡単に作業の流れを思い出すことができるようにする必要がありました。
Putty/Bashのログを何回か使ったことで、プロダクション環境での複雑な作業の順序を復元できました。このような可能性を無視しないでください。
公開
その後、私は下書きを実際のドキュメントに変換し、プロジェクトドキュメントとして公開したいと考えました。結果として、美しい境界を越えることができました。
目的は、拡張フォーマットで下書きを作成し、ドキュメントをコードのように扱うことです。
これにより、フォーマットの整備や標準的な公開形式への変換にかかる時間を節約できました。
オンライン形式
最終的に、Markdown + Gitの形式は、オンラインドキュメントを自動生成することができました。さらに、ブラウザのキャッシュによるオフラインモードも備わっており、顧客の閉じたネットワーク、飛行機中、インターネットがない場所などでも非常に役立ちました。顧客もこの機能を評価しました。
Markdownフォーマットは、GitLab、YouTrack、いくつかのチャットアプリケーションで使用され、すべてのLLMモデルで認識されています。
共有下書き
あなたの仕事に財務が関わらないのであれば、あなたの下書きは隠すべきではありません。むしろ、共同で作業できるようにすべきです。
私の下書きを公開するという意欲が、「コードとしてのドキュメント」の概念を生み出しました。DevOpsチームは、名前のないテキストファイルや「どこに書いたか？」という問題から解放され、異なるWordのバージョンや、画像が散らばった問題なども解消されました。さらに、下書きからすぐにオンライン版と、美しいPDF版が得られます。
今日のドキュメント
- Markdown形式で書かれます（Typoraなどのエディタまたは自動保存機能付きの類似エディタ、IDEA/PyCharmでのコミット）
- GitLabに保存されます（ロールベースのモデルで全社員がアクセス可能、多人数編集に対応）
- コンテナ内のDocsifyで自動的にオンライン版に変換され（コードの更新は毎分）、DNSを介してインターネットに公開されます
- Vue.jsによるサイトとファイルの両方で同じフォーマットでPDFに簡単にエクスポート可能
- 図はDrawio（アウトライン形式）とMermaid（インライン形式）で作成
- 図はSVG（まれに非互換プラットフォーム用にPNG）でエクスポートされ、統合されたソースコードも含みます
何が足りないか？大多数用户并不关心文档存储在统一的地方，也不关心是否可以在多人协作模式下编辑。贡献者（编辑）寥寥无几，而普通用户却非常多。对他们而言，重要的是能快速找到所需文档的最新版本，并能轻松分享。由此衍生出几个问题：
- 如何自动生成文档列表？
- 如何根据文档的实际更新程度（而非仅根据是否有新修订）对文本中的链接进行排序？毕竟，没人需要一个仅因表面修改而排在前列的文档。
- 允许用户直接在文档内进行小幅度编辑，无需操作源文件。
- 当文档部分相互关联、部分或全部重复使用时，如何“批量”更新文档？
- 由于文档更新速度极快，是否应考虑自动生成功能？
- 不仅要同步文档本身，还应提醒用户更新或补充相关员工在公开频道或社区中的发言。因为公众对作者（与文档相关者）的权威性评价往往比文档本身更重要——这是业已形成的事实。
第三点已在某些平台（如 Discourse）中实现，而引入 AI 将有助于实现结构化文档。