skillup

技術ブログ

ドキュメント作成

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

投稿日:

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

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

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

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

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

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

例としては

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

などでしょうか。

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

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

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

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

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

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

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

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

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

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

 

-ドキュメント作成
-

執筆者:


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

comment

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

関連記事

no image

使える設計書作成に関して

私自身、この仕事を7〜8年やっておりますが、設計書作成については常に悩まされておりました。 設計書のメリット・デメリットとしては以下のようなものですかね。 メリット メンバー間での仕様の認識を統一でき …

no image

ディレクション時に重要な視点

ディレクション(ベンダーや内製時)時に留意するポイント Contents1 開発ルールの構築2 アサインと人材スクリーニング3 言葉の共通化(特にアウトプット)4 問題化のキャッチアップ5 リソースの …

no image

APIに関して

RESTAPIのルーティングで気をつけることなんぞを。 直近のプロジェクトではRESTAPIを作ることが多かったんですが気をつけることなんぞを。 Contents1 仕様書はソースから2 ツール3 命 …

no image

開発時最低限必要かつ有用なドキュメントに関して

ウォーターフォール型の開発をかれこれ1年近くやっております。 自分がやってきた仕事とすると別職種に近いようなイメージでしたが、得ることも多かったため、ここに記しておこうと思います。 以前書いたことの記 …

no image

アジャイル開発について

エンジニアとして仕事をしてから7〜8年立ちましたが、その間9割近くはいわゆるアジャイル開発でやってきたと思っていました。今は比較的大規模な開発をしておりますので、ウォータフォールですが・・・ が、先日 …

アーカイブ