skillup

技術ブログ

ドキュメント作成

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

投稿日:

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

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

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

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

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

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

例としては

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

などでしょうか。

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

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

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

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

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

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

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

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

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

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

 

-ドキュメント作成
-

執筆者:


comment

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

関連記事

no image

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

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

no image

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

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

no image

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

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

no image

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

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

no image

ER図作成ツールについて(Mac版)

ER図作成ツールについてMacで色々と調べましたので、メモを。 フリー限定で。 ちなみにwindowsを使っていればA5:SQLが一番使えるかと思います。 以前も下記リンクで説明させていただきました。 …