どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
この記事の目的 最近「良いドキュメントが作れているな」と思う機会が増えてきたので、その知見をアウトプットしたくなった。 想定読者 今所属してる組織(会社/プロジェクトなど)のドキュメントがイマイチで悩んでいる人 そもそもドキュメントが無い組織に所属していてつらい思いをしている人 「ドキュメントを作れ」という漠然としたタスクを振られて困っている人 想定読者ではない人 メンテなブルなドキュメンテーションのエコシステムが完成している組織で更によいやり方を模索している人 私もまだ模索中なので、いいやり方があれば教えてほしいです👀 顧客提出などの「納品が必要」なドキュメントの管理方法を模索している人 この記事では「社内の情報共有」にスコープを切って話をしています 書いている人のスペック(参考) 歴５年くらいのなんちゃってフルスタックエンジニア 普段は Node.js / React.js or R
最近知った興味深い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
こんにちは。スタディサプリのWeb開発をやっている@highwideです。 今日は、自分の所属する"コーチングチーム"(個別指導コースや合格特訓コースの機能開発を行っています)が、最近のプロジェクトで利用した「アーキテクチャ・デシジョン・レコード」、通称「ADR」について紹介したいと思います。 アーキテクチャ・デシジョン・レコード(ADR)とは 「ADR」「アーキテクチャ・デシジョン・レコード」という概念を知ったのは、社内で行っていた「Design It! プログラマーのためのアーキテクティング入門」(以後「Design It!」)の読書会でのことでした。 www.oreilly.co.jp 最初にそのキーワードが登場する「11.2.3 必要なときだけ形式的な記述に投資する」では、「"膨大な量のドキュメントになる傾向"がある形式的なドキュメンテーション」に対比して、以下のように紹介されます
Talked at Cloud Native Lounge #2「クラウドネイティブなシステムの継続的改善と企業文化」. https://forkwell.connpass.com/event/215798/
こんにちは。テクノロジー本部のyoshikawaです。好きなW3C Recommendation は RDF 1.1 Concepts and Abstract Syntax です。 会議やチャットでのやり取りの決定事項・議事録、アプリケーションや機能の設計書・仕様書、READMEなどなど... LIFULLの開発現場においては、ソースコード以外にもこのように様々な文書の管理・蓄積(=ドキュメンテーション)を実施しています。 多くの開発者・メンバーがドキュメンテーションの重要性やその恩恵は理解はしているものの、なかなかうまく情報の蓄積・管理ができない、 その結果、本質的ではない調査に時間を取られてしまいDeveloper Experienceが下落してしまう。 このような課題を抱えているプロジェクトやチームは世の開発現場において少なからず存在すると思います。 LIFULLの開発現場にもこの
Jasperのコアアーキテクチャは一定間隔でGitHub APIにアクセスし、IssueやPullRequestを取得する。それをローカルのデータベースに蓄積し、そのデータベースを表示したり操作するUIを提供している。である。 主要なコンポーネントとその関係は以下の通りである。Mainプロセス・Rendererプロセス・IPCについてはElectronのプロセスモデルを参照。 画像の元ファイル Fragment(UI) Issueの更新通知、DBに保存されているIssueを表示したり、Streamの作成などを行うUIを提供 Stream Issueの検索クエリを使ってGitHub APIから最新のIssueを取得する ポーリング 全Streamの定期実行を行う Event コンポーネント間のイベント送受信の機能を提供 Repository DBを操作する機能を提供 BrowserView
こんにちは！ CData Software Japan リードエンジニアの杉本です。 大変ありがたいことに、最近あるSaaSを提供する会社さんから「リリース前のAPIを触ってみてフィードバックをくれませんか？」と依頼を受けました。 私は以前こんな記事 を公開するほど、APIどっぷりな人間なのですが、数多くの SaaS APIを触ってきてよく考えることがあります。 それは SaaS APIというサービス・プロダクトそのものを成長させる上で、もっとも重要なことは「顧客・デベロッパーが、そのAPIをどれだけスムーズにキャッチアップできるか？」という点に尽きるのではないか？ というものです。 以下のグラフはAPI管理ツールを提供するSmartBearのAPI調査において、APIドキュメントで最も重要な要素とは何か？ というアンケート結果のランキングですが、ExamplesやAuthenticati
Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? 日々Pythonの色々な記事がアップされているものの、あまりdocstringに触れている日本語の記事が少ないな・・ということで書きました。 そもそもdocstringって？ Pythonの関数だったりクラスだったりに記述するコメントです。 JSDocだったりのPython版です。 書き方は、最初結構他の言語と違うな・・という印象を受けました。 docstring書くと何が嬉しいの？ 後で見直したときに、すぐ内容が把握できるよ Guido の重要な洞察のひとつに、コードは書くよりも読まれることの方が多い、というものがあります。 はじめに
注釈 本ドキュメントは、まだ未完成ですが、ウェブフロントエンドの開発を学ぶときに、JavaScriptを経由せずに、最初からTypeScriptで学んでいく社内向けコンテンツとして作成されはじめました。基本の文法部分以外はまだ執筆されていない章もいくつもあります。書かれている章もまだまだ内容が追加される可能性がありますし、環境の変化で内容の変更が入る可能性もあります。 書籍の原稿はGitHub上で管理しております。もしTypoを見つけてくださった方がいらっしゃいましたら、 GitHub上で連絡 をお願いします 1 。reSTファイルだけ修正してもらえれば、HTML/PDFの生成までは不要です。フィードバックなども歓迎しております。 1 https://github.com/future-architect/typescript-guide/pulls
ドキュメント文化は健全な組織のスケールのために必要 組織の中でドキュメント/文章を残し活用していくことはとても重要だ。クオリティの高いドキュメントがあることで、組織に情報が流通し、透明性を確保できるようになる。情報を流通させるためにいちいち口頭の説明がいらないから、メンバーの数が増えた時でもスケールしやすくなる。過去の結論にアクセス可能になるので、議論を積み上げていき、意思決定のクオリティを高めることにもつながる。そもそも何かを読むということは何かを聞いて教わるよりも時間あたりの処理量が多いし、非同期に実施できる。良いドキュメントをアセットとして社内に蓄積していくことはスタートアップのみならず、ありとあらゆる組織が成長していく上でとても重要であると言える。 しかしその一方で、良質なドキュメント文化を徹底できている会社は多くないように見える。例えば、社内のドキュメントを蓄積させていく場所とし
WebRTC is secure,� or not secure? - WebRTC セキュリティ概説 -
VOYAGE MARKETINGの @katzchum です。 自分が携わったプロジェクトで、以下の２点を課題として、プロジェクトの進め方について検討しました。 プロジェクト立ち上げの流動的な場面でもリモートのメンバーに対しても如何に早く共通理解を促進させることが出来るか？ 開発のインプットとして、どうドキュメントを位置づけてチームへの情報の伝達手段として用いるか？ 検討した結果、以下の取組を行ないました。 ドキュメントをDSLでコード化 DSLのレビューを通じて情報共有＆ディスカッション デッドコード化させない取組（短期・長期ドキュメント） 取組のプロセスとして軽量だったわりには良い体験や気付きが得られた様に思い、プロジェクトの背景・初期の悩みから、どうアプローチして取り組んで行ったのか、振り返りも交えてお話したいと思います。 ドキュメントの悩み 新規のプロジェクト立ち上げ時にドキュメン
GoogleのDesign Docについて調べました．Design Docとは，Googleのエンジニアがソフトウエアを開発する際に必ず書くドキュメントです． 一般的にDesign Documentというと，設計仕様書のことをさすようです．設計仕様書はソフトウエアのシステム的な設計がどのように行われているかを記したドキュメントです．一方でGoogleのDesign Docは，あるソフトウエアについて，何を・なぜ・どのように作るかを記したもののようです．両者ともあつかっている対象や，対象としている読者が少しずつ異なっています．このエントリーではGoogleのDesign Docについて扱います． Design Docの内容 Design Docについては，Googleの鵜飼文敏さんによる以下のプレゼンテーションで触れられています． 鵜飼文敏さんの講演「ハッカーのソフトウェアエンジニアリング」
Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? 前置き 長年、書いてはバインダに挟まれキャビネットの奥深くにしまわれるシステム仕様書を書いてきました。 単にハンコをつくための台紙にしかならない仕様書作成ほど、エンジニアのやる気を削ぐものはありません。だからこの業界では、仕様書不要論なんてあったりするんですよね。 でも、それは間違いです。不要なのは仕様書ではなく、使われない仕様書です。 使われる仕様書を書いてみんなで幸せになりましょう。 まず読む やさしい機能仕様 - Joel on Software http://japanese.joelonsoftware.com/Article
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を作る機会が増えてきている 例えばマイクロサービス間はAPIでやりとりすることが多い。 外部のサービスもだいたいAPIでやりとりする。 社内APIもいくつかあるが、いざ使おうとなるとどんなリクエストを送るべきなのか、またどんなリクエストが返ってくるのかを調べるのが面倒。 API ドキュメントを書くのは大変 フォーマットは？ Markdown? HTML? Text? エンジニア間で書き方がバラバラにならない？ そのドキュメントの内容は今も正しい？ そもそも書くのが面倒… ということで、いい感じのAPIドキュメントツールがほしい API ドキュメントツールに求めること その1 ドキュメントが書きやすい ドキュメントが読みやすい ドキュメントがGitで管理しやすい リクエスト情報、レスポンス情報が見やすい curlですぐに試せるようにサンプルがほしい ドキュメントとコードに乖離がないよう
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く