ドキュメントに固執せよ - gfnweb
どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
メルカリShopsでのDesign Docs運用について | メルカリエンジニアリング
こんにちは! ソウゾウのSoftware Engineerの@ogataka50です。連載：メルカリShops 開発の裏側 Vol.2の9日目を担当させていただきます。 9日目はメルカリShopsを開発する中でのDesign Docsの運用について紹介させて頂きます。 Design Docsとは Design DocsとはGoogleなどで取り入れられているシステム設計ドキュメント手法です。開発をする前にプロジェクトの背景や目的、設計、検討した代案などをdocument化します。そしてそれを持って関係者との共有、議論を行うことによって事前に全体を考察し、精度を高め開発後の手戻りを減らすなどが主な目的になります。 例として、GoogleでのDesign Docsについては下記にまとめられています。 Design Docs at Google メルカリShopsでのDesign Docsのte
【保存版】Rails 5 Webpacker公式ドキュメントの歩き方+追加情報｜TechRacho by BPS株式会社
こんにちは、hachi8833です。 Rails 5のWebpackerでつらみを踏まないために、公式のWebpackerドキュメントの要点をまとめてみました。追加情報がありましたら今後も更新したいと思います。 rails/webpackerより 公式のドキュメントが分散しているのと、mdファイル名から内容が推測しにくくて見通しがよくないので、ファイルの並びを再編成して概要を一覧できるようにしました（せめてファイル名の頭に番号でも振ってくれれば...）。具体的な設定方法についてはリンク先をご覧ください。 ⚓概要 ドキュメントリポジトリ: rails/webpacker/tree/master/docs -- mdが16ファイルあります。本記事ではこちらのみを扱います。 上のドキュメントリポジトリの最終更新日: 2018/04/23 更新や誤りにお気づきの方は@hachi8833までお知らせ
わかりやすいREADME.mdを書く
GitHubなどに自分のツールやライブラリを公開するとき，README.mdは重要な役割を担っている．レポジトリを訪れたユーザが自分のツールを使ってくれるか否かの第一歩はREADME.mdにかかっている，と言っても過言ではない．実際自分が使う側になったときも，まずREADME.mdを読んで判断していると思う． 成功しているプロジェクトを参考にしつつ，自分が実践していることをまとめておく．ここに書いていることはあくまで（自分の中で）最低限的なものである．プロジェクトが成長していくにつれてREADMEはあるべき姿に成長していくべきだと思う． READMEの役割 README.mdには大きく2つの役割がある． プロジェクト，ツールの使い方，インストール方法 プロジェクト，ツールの宣伝 元々READMEは前者の役割しかなかったが，GitHubの仕組み上，後者の役割も徐々に重要になっている． さらに
Apple公式ドキュメント風のコードリファンレンスを生成·appledoc MOONGIFT
appledocはObjective-CのコードからHTMLリファレンスを生成するソフトウェア。 appledocはObjective-C製のオープンソース・ソフトウェア。外部のライブラリやフレームワークを使って開発していると、そのコードの中身を見て動作を確認する方が早くなる。そんな時に使えるのがAPIのリファレンスだ。リファレンスを使うとあたりをつけるのが早くなる。 生成されたドキュメント そのためシステム開発においてはソースコードからリファレンスを生成する系統のライブラリに人気が集まる。Objective-Cであればappledocを使ってみよう。 appledocはAppleのリファレンス風のHTMLファイルを生成するツールだ。JavaDocのようにコードに元々記述しなければならないが、その結果はとても素晴らしい。左側にツリーが、右側にコードリファレンスが表示される。必要に応じてクリ
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
Emacs Lisp 開発者にドキュメントの書き方を丁寧に教えてくれる checkdoc-minor-mode を有効にした - sheephead
