Docs As Code

チーム全体が最小限の労力で、最新かつ有用なドキュメントを提供すること
Contributed by

Alec Clews

Published July 22, 2021
Collection
1

概要

Docs As Code (“Docs Like Code”としても知られている)は、ソフトウェアプロジェクトにおけるドキュメントを提供するための一般的なアプローチです。

共通するテーマは3つあります。

  1. コンテンツ作成に、“agile”なアプローチを採用すること。
  2. チーム全体がコンテンツに責任を持つこと。
  3. 時間経過とともに、コンテンツとプロセスを適応させ、改善していくこと。ツールやプロセスは、プロジェクトに合わせて適応させる必要があります(その後のプロジェクトでもまた適応させる必要があります)。

Docs As Code イメージの著作権:Anne Gentle. MITライセンスのもとで公開されています。

メリット

  1. 価値あるドキュメントをより早く、より高い品質で提供(マルチボイス、コラボレーション)
  2. ドキュメントがリリースサイクルのボトルネックになることを防ぐ
  3. より価値の高いコンテンツ(情報アーキテクチャ、顧客体験、...)を提供するために、テクニカルライターを解放する
  4. 独自のテクニカルライティングツールの必要性をなくす

実施方法

開発者用ツールやプロセスを使用して、コンテンツを作成し、提供する。 具体例:

  1. テキストベースのファイルコンテンツに、軽量なマークアップタグを埋め込む。
  2. 開発者ベースのワークフロー。 例:
    1. Gitなどのツールを使ったバージョン管理
    2. バグや機能リクエストのチケットによる変更管理
    3. コンテンツのレビューとマージ
  3. マシンによるコンテンツ生成
  4. 自動化されたテストと検証
  5. ウェブページ(静的サイトジェネレータを使用など)またはWikiを使用した迅速なオンライン公開。 例えば SphinxHugo.

実施例

参考

Docs As Code をチームや顧客、ステークホルダーと実施するにあたりより詳細にお知りになりたい場合は、以下のリンクを参照してください。


Except where noted, content on this site is licensed under a Creative Commons Attribution 4.0 International license. This site is graciously hosted by Netlify