ドキュメントに固執せよ - gfnweb
どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
【汎用ソフトスキル】ドキュメンテーションの続け方
この記事の目的 最近「良いドキュメントが作れているな」と思う機会が増えてきたので、その知見をアウトプットしたくなった。 想定読者 今所属してる組織(会社/プロジェクトなど)のドキュメントがイマイチで悩んでいる人 そもそもドキュメントが無い組織に所属していてつらい思いをしている人 「ドキュメントを作れ」という漠然としたタスクを振られて困っている人 想定読者ではない人 メンテなブルなドキュメンテーションのエコシステムが完成している組織で更によいやり方を模索している人 私もまだ模索中なので、いいやり方があれば教えてほしいです👀 顧客提出などの「納品が必要」なドキュメントの管理方法を模索している人 この記事では「社内の情報共有」にスコープを切って話をしています 書いている人のスペック(参考) 歴５年くらいのなんちゃってフルスタックエンジニア 普段は Node.js / React.js or R
「Docs for Developers」を読んだ - 勘と経験と読経
最近知った興味深いPodcast e34.fm で紹介されていたので興味を持って読んでみた本「Docs for Developers: An Engineer’s Field Guide to Technical Writing」に関するメモ。 2023/3追記：翻訳されたようだ。ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング e34.fmwww.oreilly.com この記事の目次 「Docs for Developers」はどんな本なのか 全般的な感想 各章に関する覚え書き Front Matter Chap 1. Understanding your audience Chap 2. Planning your documentation Chap 3. Drafting documentation Chap 4. Editing docum
〜その意思決定を刻め〜「アーキテクチャ・デシジョン・レコード(ADR)」を利用した設計の記録 - スタディサプリ Product Team Blog
こんにちは。スタディサプリのWeb開発をやっている@highwideです。 今日は、自分の所属する"コーチングチーム"(個別指導コースや合格特訓コースの機能開発を行っています)が、最近のプロジェクトで利用した「アーキテクチャ・デシジョン・レコード」、通称「ADR」について紹介したいと思います。 アーキテクチャ・デシジョン・レコード(ADR)とは 「ADR」「アーキテクチャ・デシジョン・レコード」という概念を知ったのは、社内で行っていた「Design It! プログラマーのためのアーキテクティング入門」(以後「Design It!」)の読書会でのことでした。 www.oreilly.co.jp 最初にそのキーワードが登場する「11.2.3 必要なときだけ形式的な記述に投資する」では、「"膨大な量のドキュメントになる傾向"がある形式的なドキュメンテーション」に対比して、以下のように紹介されます
緩やかに死んでいくシステム / You won't be in the team forever
Talked at Cloud Native Lounge #2「クラウドネイティブなシステムの継続的改善と企業文化」. https://forkwell.connpass.com/event/215798/
継続的ドキュメンテーション: Github DiscussionsとADRのすすめ - LIFULL Creators Blog
こんにちは。テクノロジー本部のyoshikawaです。好きなW3C Recommendation は RDF 1.1 Concepts and Abstract Syntax です。 会議やチャットでのやり取りの決定事項・議事録、アプリケーションや機能の設計書・仕様書、READMEなどなど... LIFULLの開発現場においては、ソースコード以外にもこのように様々な文書の管理・蓄積(=ドキュメンテーション)を実施しています。 多くの開発者・メンバーがドキュメンテーションの重要性やその恩恵は理解はしているものの、なかなかうまく情報の蓄積・管理ができない、 その結果、本質的ではない調査に時間を取られてしまいDeveloper Experienceが下落してしまう。 このような課題を抱えているプロジェクトやチームは世の開発現場において少なからず存在すると思います。 LIFULLの開発現場にもこの
なぜその API は使われないのか？ API の活用を拒む3つの壁とその対策 - CData Software Blog
こんにちは！ CData Software Japan リードエンジニアの杉本です。 大変ありがたいことに、最近あるSaaSを提供する会社さんから「リリース前のAPIを触ってみてフィードバックをくれませんか？」と依頼を受けました。 私は以前こんな記事 を公開するほど、APIどっぷりな人間なのですが、数多くの SaaS APIを触ってきてよく考えることがあります。 それは SaaS APIというサービス・プロダクトそのものを成長させる上で、もっとも重要なことは「顧客・デベロッパーが、そのAPIをどれだけスムーズにキャッチアップできるか？」という点に尽きるのではないか？ というものです。 以下のグラフはAPI管理ツールを提供するSmartBearのAPI調査において、APIドキュメントで最も重要な要素とは何か？ というアンケート結果のランキングですが、ExamplesやAuthenticati
[Python]可読性を上げるための、docstringの書き方を学ぶ（NumPyスタイル） - Qiita
日々Pythonの色々な記事がアップされているものの、あまりdocstringに触れている日本語の記事が少ないな・・ということで書きました。 そもそもdocstringって？ Pythonの関数だったりクラスだったりに記述するコメントです。 JSDocだったりのPython版です。 書き方は、最初結構他の言語と違うな・・という印象を受けました。 docstring書くと何が嬉しいの？ 後で見直したときに、すぐ内容が把握できるよ Guido の重要な洞察のひとつに、コードは書くよりも読まれることの方が多い、というものがあります。 はじめに — pep8-ja 1.0 ドキュメント 最初は少し時間がかかっても、書いておくと後でコードを読み直した時の負担が減ります。 関数などを扱う際に、内容を見たりできるよ jupyter などであれば、nbextentionsでhinterlandを有効化する
![[Python]可読性を上げるための、docstringの書き方を学ぶ（NumPyスタイル） - Qiita](https://cdn-ak-scissors.b.st-hatena.com/image/square/dfaa047843f04e332970c0a74f1e00605d8ee219/height=288;version=1;width=512/https%3A%2F%2Fqiita-user-contents.imgix.net%2Fhttps%253A%252F%252Fcdn.qiita.com%252Fassets%252Fpublic%252Farticle-ogp-background-412672c5f0600ab9a64263b751f1bc81.png%3Fixlib%3Drb-4.0.0%26w%3D1200%26mark64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZ3PTk3MiZoPTM3OCZ0eHQ9JTVCUHl0aG9uJTVEJUU1JThGJUFGJUU4JUFBJUFEJUU2JTgwJUE3JUUzJTgyJTkyJUU0JUI4JThBJUUzJTgxJTkyJUUzJTgyJThCJUUzJTgxJTlGJUUzJTgyJTgxJUUzJTgxJUFFJUUzJTgwJTgxZG9jc3RyaW5nJUUzJTgxJUFFJUU2JTlCJUI4JUUzJTgxJThEJUU2JTk2JUI5JUUzJTgyJTkyJUU1JUFEJUE2JUUzJTgxJUI2JUVGJUJDJTg4TnVtUHklRTMlODIlQjklRTMlODIlQkYlRTMlODIlQTQlRTMlODMlQUIlRUYlQkMlODkmdHh0LWFsaWduPWxlZnQlMkN0b3AmdHh0LWNvbG9yPSUyMzIxMjEyMSZ0eHQtZm9udD1IaXJhZ2lubyUyMFNhbnMlMjBXNiZ0eHQtc2l6ZT01NiZzPThhMGJmMmI1MzM2NDVlNDBlM2UyZGZjNDg1NGJmNTlj%26mark-x%3D142%26mark-y%3D57%26blend64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZoPTc2Jnc9NzcwJnR4dD0lNDBzaW1vbnJpdGNoaWUmdHh0LWNvbG9yPSUyMzIxMjEyMSZ0eHQtZm9udD1IaXJhZ2lubyUyMFNhbnMlMjBXNiZ0eHQtc2l6ZT0zNiZ0eHQtYWxpZ249bGVmdCUyQ3RvcCZzPTAzNTFhOWFiMzVlNjQwNDIxNzY0MDEzZTMzZTZhNmZk%26blend-x%3D142%26blend-y%3D486%26blend-mode%3Dnormal%26s%3D2c9035999f00da0029accbe8604c4563)
仕事ですぐに使えるTypeScript — 仕事ですぐに使えるTypeScript ドキュメント
注釈 本ドキュメントは、まだ未完成ですが、ウェブフロントエンドの開発を学ぶときに、JavaScriptを経由せずに、最初からTypeScriptで学んでいく社内向けコンテンツとして作成されはじめました。基本の文法部分以外はまだ執筆されていない章もいくつもあります。書かれている章もまだまだ内容が追加される可能性がありますし、環境の変化で内容の変更が入る可能性もあります。 書籍の原稿はGitHub上で管理しております。もしTypoを見つけてくださった方がいらっしゃいましたら、 GitHub上で連絡 をお願いします 1 。reSTファイルだけ修正してもらえれば、HTML/PDFの生成までは不要です。フィードバックなども歓迎しております。 1 https://github.com/future-architect/typescript-guide/pulls
スケールする組織を支えるドキュメンテーションの技術を”GitLab Handbook”から学ぶ｜Anno Takahiro
ドキュメント文化は健全な組織のスケールのために必要 組織の中でドキュメント/文章を残し活用していくことはとても重要だ。クオリティの高いドキュメントがあることで、組織に情報が流通し、透明性を確保できるようになる。情報を流通させるためにいちいち口頭の説明がいらないから、メンバーの数が増えた時でもスケールしやすくなる。過去の結論にアクセス可能になるので、議論を積み上げていき、意思決定のクオリティを高めることにもつながる。そもそも何かを読むということは何かを聞いて教わるよりも時間あたりの処理量が多いし、非同期に実施できる。良いドキュメントをアセットとして社内に蓄積していくことはスタートアップのみならず、ありとあらゆる組織が成長していく上でとても重要であると言える。 しかしその一方で、良質なドキュメント文化を徹底できている会社は多くないように見える。例えば、社内のドキュメントを蓄積させていく場所とし
Google エンジニアリング・プラクティス ドキュメント
Google エンジニアリング・プラクティス ドキュメント このページは、Google Engineering Practices Documentation の非公式な日本語翻訳です。元のドキュメントは、クリエイティブ・コモンズの「CC-By 3.0」ライセンスで公開されています。 Google には、あらゆる言語・あらゆるプロジェクトをカバーする一般化されたエンジニアリング・プラクティスが数多く存在します。こうしたドキュメントは、私たちが長年に渡って開発してきたさまざまなベストプラクティスの経験が集結したものとなっています。オープンソース・プロジェクトやその他の組織でも、こうした知識から恩恵を受けられるかもしれません。そのため、私たちは可能な限り、この知識を公開するように努めています。 現在、以下のドキュメントが公開されています。 Google コードレビューガイドライン (Googl
GitHubでポータルサイトドキュメントを運営して幸せになる話
WebRTC is secure,� or not secure? - WebRTC セキュリティ概説 -
非同期コミュニケーションにおけるドキュメント - CARTA TECH BLOG
VOYAGE MARKETINGの @katzchum です。 自分が携わったプロジェクトで、以下の２点を課題として、プロジェクトの進め方について検討しました。 プロジェクト立ち上げの流動的な場面でもリモートのメンバーに対しても如何に早く共通理解を促進させることが出来るか？ 開発のインプットとして、どうドキュメントを位置づけてチームへの情報の伝達手段として用いるか？ 検討した結果、以下の取組を行ないました。 ドキュメントをDSLでコード化 DSLのレビューを通じて情報共有＆ディスカッション デッドコード化させない取組（短期・長期ドキュメント） 取組のプロセスとして軽量だったわりには良い体験や気付きが得られた様に思い、プロジェクトの背景・初期の悩みから、どうアプローチして取り組んで行ったのか、振り返りも交えてお話したいと思います。 ドキュメントの悩み 新規のプロジェクト立ち上げ時にドキュメン
Google の Design Doc について
GoogleのDesign Docについて調べました．Design Docとは，Googleのエンジニアがソフトウエアを開発する際に必ず書くドキュメントです． 一般的にDesign Documentというと，設計仕様書のことをさすようです．設計仕様書はソフトウエアのシステム的な設計がどのように行われているかを記したドキュメントです．一方でGoogleのDesign Docは，あるソフトウエアについて，何を・なぜ・どのように作るかを記したもののようです．両者ともあつかっている対象や，対象としている読者が少しずつ異なっています．このエントリーではGoogleのDesign Docについて扱います． Design Docの内容 Design Docについては，Googleの鵜飼文敏さんによる以下のプレゼンテーションで触れられています． 鵜飼文敏さんの講演「ハッカーのソフトウェアエンジニアリング」
仕様書を意味があるものにするために気をつけるべき3つのこと - Qiita
前置き 長年、書いてはバインダに挟まれキャビネットの奥深くにしまわれるシステム仕様書を書いてきました。 単にハンコをつくための台紙にしかならない仕様書作成ほど、エンジニアのやる気を削ぐものはありません。だからこの業界では、仕様書不要論なんてあったりするんですよね。 でも、それは間違いです。不要なのは仕様書ではなく、使われない仕様書です。 使われる仕様書を書いてみんなで幸せになりましょう。 まず読む やさしい機能仕様 - Joel on Software http://japanese.joelonsoftware.com/Articles/PainlessFunctionalSpecifi-2.html 読んだ？ 大丈夫。長いけれど面白いのでするする読めます。 この知識が一番ベースになります。 で、読んだ？ はい。 読んだあなたには、仕様書が必要だということ、どのような仕様書を書けばそれが
Swagger-PHPについてLaravel 5.2で確認したメモ – hrendoh's tech memo
SwaggerのPHP実装であるSwagger-PHPの使い方についてLaravelプロジェクトで確認し、Swaggerとはどんなものか調査したメモになります。 Swaggerの全体像については、「RESTful APIの記述標準化を担うSwaggerとは？ | NTT Communications Developer Portal」が参考になりました。 Swaggerを利用したアプリケーション開発は、まずSwaggerドキュメントを作成して、サーバーのスタブとクライアントライブラリを生成し、APIロジックとクライアントUIなどを実装していくような流れになるといったところのようです。 Laravelはありませんが、コード生成ツール swagger-codegen には、Laravelの軽量版であるLumen用のサーバースタブは生成可能です。 この記事では、Laravel 5.2プロジェクト
API Blueprintとその周辺ツール - Qiita
APIを作る機会が増えてきている 例えばマイクロサービス間はAPIでやりとりすることが多い。 外部のサービスもだいたいAPIでやりとりする。 社内APIもいくつかあるが、いざ使おうとなるとどんなリクエストを送るべきなのか、またどんなリクエストが返ってくるのかを調べるのが面倒。 API ドキュメントを書くのは大変 フォーマットは？ Markdown? HTML? Text? エンジニア間で書き方がバラバラにならない？ そのドキュメントの内容は今も正しい？ そもそも書くのが面倒… ということで、いい感じのAPIドキュメントツールがほしい API ドキュメントツールに求めること その1 ドキュメントが書きやすい ドキュメントが読みやすい ドキュメントがGitで管理しやすい リクエスト情報、レスポンス情報が見やすい curlですぐに試せるようにサンプルがほしい ドキュメントとコードに乖離がないよう
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
GitHub - docuowl/docuowl: 🦉 A documentation generator
jasper/ARCHITECTURE.md at master · jasperapp/jasper
docsify