GitLab的ドキュメント文化を組織にインストールする（実践編:スタートアップMNTSQの事例）｜Anno Takahiro
会社組織にドキュメント文化をインストールすることの有用性や、GitLabのような企業がどのようにドキュメントを運用しているかを、前回記事で書いた（スケールする組織を支えるドキュメンテーションの技術を”GitLab Handbook”から学ぶ）。今回は、私のいるスタートアップのMNTSQ（モンテスキュー、と読みます）でどのようにそれを実践しているか、実際のところどのような成果が出ているのかについて書いてみたい。 MNTSQでは、当初からドキュメンテーションの重要性を経営メンバー全員で認識しており、社内ドキュメントをGitHub管理でメンテナンスしながら作り上げていくようにしていた。この大枠の仕組みの設計部分は弊社のデザイナーの生谷(@ikutani41)が初期に考案/メンテしたものである。デザイナー視点からこのような仕組みが設計され稼働されることは珍しいと思う。この辺については本人からもどう
スケールする組織を支えるドキュメンテーションの技術を”GitLab Handbook”から学ぶ｜安野貴博
ドキュメント文化は健全な組織のスケールのために必要 組織の中でドキュメント/文章を残し活用していくことはとても重要だ。クオリティの高いドキュメントがあることで、組織に情報が流通し、透明性を確保できるようになる。情報を流通させるためにいちいち口頭の説明がいらないから、メンバーの数が増えた時でもスケールしやすくなる。過去の結論にアクセス可能になるので、議論を積み上げていき、意思決定のクオリティを高めることにもつながる。そもそも何かを読むということは何かを聞いて教わるよりも時間あたりの処理量が多いし、非同期に実施できる。良いドキュメントをアセットとして社内に蓄積していくことはスタートアップのみならず、ありとあらゆる組織が成長していく上でとても重要であると言える。 しかしその一方で、良質なドキュメント文化を徹底できている会社は多くないように見える。例えば、社内のドキュメントを蓄積させていく場所とし
APIのエラーハンドリングを見直そう - WebPay Engineering Blog
ここ数ヶ月にわたって、WebPayはAPIのエラーにまつわる変更を少しずつ行ってきました。 それに付随してドキュメントも拡張しましたが、変更の背景について十分に説明できていない部分がありました。 この記事では、最近のエラーに関連した変更の背景を紹介し、今後どのようにエラーをハンドルすべきか説明します。 記事の内容は執筆時点のものであり、今後同じようにエラーやAPIの変更を行うことがあります。 変更があっても記事の内容はその時点の内容を保持し、ウェブサイトのドキュメントのみ更新します。 必ずウェブサイトのドキュメントを合わせて参照し、手元で動作確認を行ってください。 エラーはなぜ起きるのか WebPayのAPIは、リクエストされた操作ができなかったときにエラーを返すように設計しています。 可能なかぎりエラーにならないような設計、実装を心がけていますが、エラーは絶対に避けられません。 例えば、
ドキュメント作成に参考になる公開ドキュメント集
Webシステムにてドキュメントを作る際に参考になる公開されているドキュメントを集めてみました。 見た限りはどれも無償で利用可能なようですが、実際に利用される際は規約等をご確認下さい。 発注者ビューガイドライン http://sec.ipa.go.jp/reports/20080710.html 形式：[PDF] IPAが公開しているドキュメント作成ガイドラインです。 発注者とSIerの間で意思疎通を図ることを目的としているので、内容も詳細でかつ分かりやすいです。分量がかなり多いのですが、JavaでおなじみのPet Storeを題材に具体的なドキュメントが載っているので、ざっと見てみるだけでも参考になると思います。 ただ小規模案件だと、このガイドラインどおりに全てのドキュメントを揃えるのはムリがあると思うので、使えそうな部分だけ上手く利用するのが良いでしょう。 関連書籍も出ているようなので、
システム開発の仕様書テンプレートや参考サイトのまとめ｜IT情報局
システム開発の際に必要になる要求仕様書や基本設計、詳細設計に使う各種の書類のテンプレートを紹介しているサイトをまとめました。 また、参考になる資料を配布しているサイトや開発関連資料の書き方などの説明をしているサイトもあります。 システムを開発時の書式や方法は各プロジェクトによって使うフォーマットは異なりますが、初めて開発する場合や自社での開発資料を作成する際のテンプレートとして参考にしてください。 2017/2/22 追記 リンク先の資料を配布しているサイトがかなり古くなってしまったのでリンクの見直しと、新たにシステム開発の資料を提供しているサイトを探して追加しました。 仕様書のダウンロードができるサイト Pocket 9 要求仕様書から見積、基本設計、詳細設計、コーディング規約、テスト仕様書、その他スケジュールや議事録まで システム開発に必要な書類のテンプレートがそろっています。 htt
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
Logdown - Site Maintenance