skillup

技術ブログ

ドキュメント作成

ドキュメント作成について

投稿日:

アプリやプロジェクトのドキュメント作りですが、時間が立ったり、複数人での開発を行うと

  • 情報の漏れや抜けが非常に多くなる
  • 本番との差分ができる
  • 一部の人しか更新しなくなる
  • 似たようなドキュメントがあちこちにできる

などなど完全には機能しなくなることが一般的です。

人間がやる以上、完全に機能させることは難しいのですが、

大原則としてシステムやコードから起こすのが大切になってくると思います。またそのドキュメントを作らないとプロジェクトが進まないようにすることも大切だと思います。

それを体系化したものがCIという考えだと思いますが、要点としては開発に絶対必要なプロセスに組み込むことだと思います。

例としては

  • Gitのpushの際にドキュメントを作る
  • ドキュメントのプロセスがないと本番にpullできない

などでしょうか。

ちなみに自分は一人で開発を進めることも多かったため、あまりドキュメントを残さずにとりあえずコードを書くということが一般的でした・・(汗)

最近はサーバーとフロント側で仕事を分けたりして進めることが多いのですが、そうなるとどうしても情報を共有する必要が出てきます。

また短納期、小規模な開発が多かったため、ゆったりと開発することはできません。

私はドキュメント作成があまり好きではないのですが、機能しなくなるのと、そのための開発時間を取られるからです。

それを両立する方法はないかな、と頭を悩ませていました。

色々試行錯誤し、まだ実験段階ですが、テストコードの活用が鍵になる気がします。

テストコードを作る過程でドキュメント作成(あるいはそれに相当するもの)を作ることができるからです。

もちろんコードの書き方自体が正しい必要はありますが、テストコードをうまく書くことによって

  • システムからドキュメントを作れる
  • ドキュメント作りの時間(開発できない時間)がへる

といったことが実現できるのではないかと思います。

 

-ドキュメント作成
-

執筆者:


comment

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

関連記事

no image

業務管理アプリの商品コードに関して

一般的な業務管理アプリを作っていると商品や顧客などもオートインクリメントのidではなく、独自の仕様で決められた「商品コード」などを持っていることが一般的です。 昔通販がらみのシステムを使っている時も商 …

no image

コレクションの頻出処理に関して

PHPでコレクションを使っていますが、慣れると本当に便利ですね・・・まあforeachとかでグリグリやってもいいのですが、無駄にコードが長くなります。 自分がコレクションでよく使う再頻出のメソッドなど …

no image

新アプリの本番環境デプロイについて

新しく作ったWEBアプリを本番配置しようとしたんですが、何度もやっているはずの処理がいざやろうとするといろいろと手間取ってしまい、1時間近くかかりました。 容量悪いなーと思いつつ、こういった行為はなる …

no image

データベースのテスト環境作成

現在作っているシステムのリリースが近づいており、本番に近い環境を作成しお客様に見てもらうことに。 こういった手順はマニュアル化しておいたほうが楽だろうと思い、自分的にメモ 1 現状運用されているデータ …

no image

ドメイン決定&業務フローとの対応確認

Contents1 ドメイン決定2 業務フローとの対応2.1 実際の業務とエンティティ、画面の遷移2.2 ドメインのCRUD分析 ドメイン決定 業務フローを抽出し、エンティティを抽出した段階で次にドメ …