Design Docs at Google
One of the key elements of Google's software engineering culture is the use of design docs for defining software designs. These are relatively informal documents that the primary author or authors of a software system or application create before they embark on the coding project. The design doc documents the high level implementation strategy and key design decisions with emphasis on the trade-of
ドキュメントに固執せよ - gfnweb
どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
ドキュメント駆動開発v2
前提 ここで言っているドキュメントは仕様書ではなく、顧客向け製品ドキュメント。 ミドルウェア製品を開発 小さなチーム パッケージ製品とパッケージ製品のクラウド版 そのため顧客に提供するドキュメントが必ず必要 GitHub を利用 自分で開発する場合のフロー 作りたい機能をぼんやりでいいので GitHub Issue に追加する feature ブランチを切る デザインドキュメントをリポジトリの doc/ 以下に書く デザインドキュメントに合わせてコーディングを進めてなんとなく動くところまで作る 動かなくてもいいのでイメージを膨らませるためにコードを書いてみる デザインドキュメントは書き捨て前提で、とにかくメモを書く 製品ドキュメントを書き始めて、一旦書き終える ブランチマージに向けてコーディングを進める 書ける範囲でテストを書く ドキュメントを平行して修正する プルリクエストをだしてレビュ
プログラムの「アーキテクチャに関するドキュメント」は面倒でも書くべき、ではどのように書くべきか？
開発プロジェクトに新しく加わった時は、まずプロジェクトの理解が第一。しかし、全体像を把握できるようなドキュメントがなく、コードから断片的な情報をかき集めるしかない場合もあります。新参の開発者がスムーズにプロジェクトを理解できるよう、大規模なプロジェクトでは「プロジェクト全体のアーキテクチャ」を示した「ARCHITECTURE.md」を添えた方がよいと、エンジニアのAleksey Kladov氏が指摘しています。 ARCHITECTURE.md https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html Kladov氏はオープンソースプロジェクトの開発に携わる中で、「プロジェクトのアーキテクチャに対する知識量」によって開発スピードに大きな差が生じると気づいたとのこと。アーキテクチャに関する知識がない開発者にとって、大量のコードは「バラ
スケールする組織を支えるドキュメンテーションの技術を”GitLab Handbook”から学ぶ｜Anno Takahiro
ドキュメント文化は健全な組織のスケールのために必要 組織の中でドキュメント/文章を残し活用していくことはとても重要だ。クオリティの高いドキュメントがあることで、組織に情報が流通し、透明性を確保できるようになる。情報を流通させるためにいちいち口頭の説明がいらないから、メンバーの数が増えた時でもスケールしやすくなる。過去の結論にアクセス可能になるので、議論を積み上げていき、意思決定のクオリティを高めることにもつながる。そもそも何かを読むということは何かを聞いて教わるよりも時間あたりの処理量が多いし、非同期に実施できる。良いドキュメントをアセットとして社内に蓄積していくことはスタートアップのみならず、ありとあらゆる組織が成長していく上でとても重要であると言える。 しかしその一方で、良質なドキュメント文化を徹底できている会社は多くないように見える。例えば、社内のドキュメントを蓄積させていく場所とし
メンテナンス作業手順の書き方
この記事は「ex-KAYAC Advent Calendar 2018」の11日目の記事です(遅れてすみません 🙇)。 カヤックでの私について⌗ソーシャルゲームのバックエンドエンジニアとして 3 ヵ月、クライアントワークのバックエンドエンジニアとして9 ヵ月の経験を積んだ後、Web のインフラエンジニア(以降、インフラエンジニア)として 4年半従事しました(2018年12月現在、中途採用ページを見るとインフラエンジニアになっていましたが、現在は SRE になっているはずです)。 主にソーシャルゲームの担当で、社内評価システムの実装・運用・保守や Redmine を定期的にアップグレードしたりもしていました。 もともとインフラエンジニア志望だったのですが、私が新卒入社したころはインフラの上で動くアプリケーションのこともわからないといけないということで、まずはバックエンドのエンジニアとして経
｢手順書｣のススメ - Masteries
こんにちは, id:papix です. この記事は, ｢はてなエンジニア Advent Calendar 2018｣の9日目の記事です. qiita.com 昨日は id:wtatsuru さんによる, ｢基盤開発観点からみたはてなのAWS活用のこれまでとこれから｣でした. wtatsuru.hatenadiary.com ｢手順書｣のススメ さて, 早速本題に入っていきましょう. 皆さんは｢手順書｣を書いていますか? 自分はと言うと, 最近そこそこの規模のオペレーションが必要なタスクを担当する機会が多く, その度に手順書を書いて, レビューしてもらってからオペレーションをするようにしています. 例えば, 今年実施した｢はてなが提供するドメインを利用したブログのHTTPS化対応｣のリリースの時は, このような手順書を書いていました: この時は, GitHubのIssueに手順書を用意してい
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
