skillup

技術ブログ

ドキュメント作成

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

投稿日:

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

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

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

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

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

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

例としては

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

などでしょうか。

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

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

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

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

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

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

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

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

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

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

 

-ドキュメント作成
-

執筆者:


  1. […] ドキュメント作成について […]

comment

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

関連記事

no image

バッチスクリプトで気をつけたい点

実務でバッチ処理を作る際に気をつけるべきと思ったこと。 基本的にエラーをいかに捉えていかにログに吐くかを最初に考える。まずはエラーありき。失敗するもの、想定した値がこない、あるいは値がないを前提として …

no image

ファジープロジェクト対策 その1

5月ぐらいから着手していたプロジェクト(顧客管理ソフト)が終焉を迎え、検証段階に入ったので、記して置きたいことなど。 数ヶ月程度ですが、自分が携わったプロジェクトの中では過去最大クラスのものでした。 …

no image

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

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

no image

コード静的解析ツールを使った際の気づきなど

最近のプロジェクトでコード静的解析ツール(phpcs,phpmd)を使った際の気づきなど コードを書きながら常時エディタがチェックするタイプのものでないとまず無理(保存するたびでも無理だし、コミット時 …

no image

小〜中規模程度のWEBアプリ作成で気をつけるべきこと

初見の処理系(ライブラリ操作)などは休日などで最小パターンを確認しておくこと。実務で何時間も悩むと非常にストレスがたまる テーブル設計命。あとで終えるようにトレースができるような値を入れておくこと。 …