社内ドキュメントはなぜ更新されないのか？情報の鮮度を最小限の運用負荷で維持する「イミュータブルドキュメントモデル」のススメ - KAKEHASHI Tech Blog
はじめに こんにちは。カケハシの各プロダクトを支えるプラットフォームシステムの開発チームでテックリードを担当しているkosui(@kosui_me)です。 プロダクト開発の世界では、明瞭な社内向けドキュメントを書くための方法が数多く提案されてきました。読者の中には、製品要求を明瞭にするためにPRD (Product Requirements Document、製品要求仕様書) を書き、プロジェクトの背景から全体の設計やその代案について明瞭にするためにDesign Docsを書き、アーキテクチャに関する意思決定の記録を明瞭にするためにADR(Architecture Decision Record) を書いてきた方も数多くいらっしゃると思います。 しかし、どんな素晴らしいドキュメントも、何故か更新されなくなります。新メンバーへのオンボーディングのためにインフラ構成図を検索したあなたが見つけた
インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。まずは、本書籍の概要について話します。 本セッションの対象者と、セッションのゴール 岩瀬義昌氏：ご紹介いただきました、岩瀬と申します。よろしくお願いします。『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』は、もともと『Docs for Developers: An Engineer’s Field Guide to Technical Writing』という洋書だったんですが、その翻訳をして、今回この機会をいただいています。 余談ですが、APC（株式会社エーピーコミュニケーションズ）さんが「カプセルト
2004年1月2月に放送された番組だが、先日の11月8日9日の深夜に再放送された。今はNHKプラスの配信で一週間見ることができる。 選「ドキュメント・エルサレム」(前編) - NHKスペシャル - NHK https://www.nhk.jp/p/special/ts/2NY2QQLPM3/episode/te/MV8W36W6XX/ （追記：後編のURLもつけときます。選「ドキュメント・エルサレム」(後編) - NHKスペシャル - NHK https://www.nhk.jp/p/special/ts/2NY2QQLPM3/episode/te/XZR9W44JV3/ ） 最近作られた「映像の世紀」とかのイスラエルドキュメンタリーやパレスチナ紛争の解説番組なんかと比べてよっぽど中身があった。 イスラエルの穏健派政治家たちが和平を結ぼうとするたびに、虐殺者シャロン率いるリクードなどの大イ
安野モヨコが夫・庵野秀明のドキュメントを見たら「カメラの前でほとんど心を開かないままに終わったのでひっくり返った」。監督の＜断固として＞との姿勢を生き方の指針に 還暦不行届｜話題｜婦人公論.jp
漫画『ハッピー・マニア』で人気を博し、その後の作品『シュガシュガルーン』では第29回講談社漫画賞を受賞するなど、数々の名作を生み出している、漫画家・安野モヨコさん。そして、安野さんのパートナーはアニメ『新世紀エヴァンゲリオン』の監督・庵野秀明さん。このクリエイティブなご夫婦は一体どんな生活を送っているのでしょうか。安野さんは、「監督は眠っている時の姿が浜辺に打ち上げられた棒みたい」と言っていて――。 集中力 監督は眠っている時の姿が変わっていて 浜辺に打ち上げられた棒みたいに一本になって寝ている。 体の中にある本体が抜け出して、その際入れ物である肉体を ぽいと投げ出して出かけてった、というような感じがする。 なんでそんなふうに感じるかというと 普段から監督の動きがそんな様子だからだ。
Jira SoftwareやTrelloなどを中心としたPMが経験してきたプロダクト管理ツールの失敗や改善を語る「本当に使いこなせてる？プロダクト管理ツールの失敗&改善PMトーク【開発PM勉強会 vol.20】」。ここで株式会社ビズリーチの菊池氏が登壇。ドキュメント管理とプロダクトバックログの失敗から学ぶツール運用のコツについて紹介します。 菊池氏の自己紹介 菊池信太郎氏（以下、菊池）：ビズリーチの菊池から、10分枠で話をします。今日のテーマは「失敗から学ぶドキュメントとチケット運用のコツ」ということで、今まで経験したところで「こういうアンチパターンがあったよ」「こういう改善をしたよ」というようなところをお話しできればと思っています。 自己紹介を軽くすると、（私は）2018年からビズリーチで働いています。ビズリーチサービスを作っていて、プラットフォーム開発部の部長をしています。また、201
はじめにTIG真野です。 秋のブログ週間2023 の3本目は、設計ドキュメントをGit管理して腐らせないようにがんばってみた話をします。 前段として6年前、「我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか」という記事を書いたのですが、その後の試行錯誤はどこにも残していないことに気づきました。普段のフューチャー技術ブログですとちょっと引け目を感じるテーマですが、秋の夜長を楽しむため読み物成分を多めに書くというテーマのこのブログリレーにピッタリな気がするため、この機会をお借りします。 ドキュメントも色々な種別があるかと思いますが、この記事では設計ドキュメントを指すことにします。設計ドキュメントは開発メンバーが参照するもので、ステークホルダーへの説明資料に引用して使うことはあれど、主目的は異なるという前提です。Design Docの場合もありますし、システム構成図、ERD、
「すげえ。パクってやがる。ここまでクズども、見たことねえ」小説落選、青葉被告が徐々に過激行動へ 大宮駅前無差別殺人事件計画を初めて語る【ドキュメント京アニ裁判⑦被告人質問】 | TBS NEWS DIG
「すげえ。パクってやがる。ここまでクズども、見たことねえ」小説落選、青葉被告が徐々に過激行動へ 大宮駅前無差別殺人事件計画を初めて語る【ドキュメント京アニ裁判⑦被告人質問】
選「ドキュメント・エルサレム」(前編) - NHKスペシャル
ユダヤ教、キリスト教、イスラム教の三つの宗教の聖地、エルサレム。３０００年にわたり様々な衝突の震源地となってきた。世界を揺るがしている紛争がどのように始まったのかを、二組の父子と貴重な記録映像で検証する。２回シリーズの前編。
シンプルに自己アピールで勝負 ソフトウェアエンジニアのコニー・リー（33）は昨年、恋人と別れた後、ふたたびマッチングアプリを使うようになった。しかし、そこで出会った男性の多くはカジュアルな関係を求めているようだったので、彼女は違う方法を試してみることにした。 それは、記事1本分ほどもある長い履歴書のようなプロフィールを書くことだった。デート相手を探すために、レジュメのような長い自己紹介文を他人がオンラインで公開しているのを見たことがあったのだ。
エンジニアに英語力が必要な本当の理由を知ってますか？「英語でしか存在しないドキュメントを読むため？」「違いますね」→許したくない事案がココにある
米村歩@日本一残業の少ないIT企業社長 @yonemura2006 エンジニアが英語力が必要な本当の理由を知ってますか？英語でしか存在しないドキュメントを読むため？違いますね。ずばり、センスの欠片も感じられない変数名やメソッド名を付けないようにするためですよ。あれやるやつマジ許さん。 2024-05-23 18:16:07
マイクロソフト、GPT-4に任意のドキュメントなどを読み込ませて回答してもらえる「Azure OpenAI Service On Your Data」が正式サービスに
マイクロソフトは、GPT-35-TurboもしくはGPT-4に任意のデータソースを指定することでそのデータの内容を読み込み、質問に対して内容を基に回答できるようになる新機能「Azure OpenAI On Your Data」が正式サービスとなったことを発表しました。 例えば、社内規約や社内マニュアルなどを読み込ませると、「PCの修理を申し込むための社内手続きは？」といった、汎用の知識だけしか持たない従来のGPTでは答えられない質問にも回答できるようになります。 任意のドキュメントを読み込ませるための支援ツール「Azure AI Studio」には、Azure OpenAI On Your DataでカスタマイズしたAIを、チャットボットとして公開する機能も備わっています。 カスタマイズしたチャットAIのサービスを、社内や社外に簡単に公開できるようになります。 Azure OpenAI S
本記事の要約 ドキュメントを書かない事は、企業やチームの「負債」になる ドキュメントを書かない事は、自身の学びや振り返りの「機会損失」になる そういう文化が根付く前に、負の連鎖を断ち切ろう！ はじめに 世の中のプロジェクトには、ドキュメントが足りていない、と感じています。 でも残念な事に、ドキュメントをどうしても書きたい人は「ほとんどいない」と思います。 その一方で「ドキュメントを書いた方が良い」という事は、 何となく分かっている人も多いと思います。 やりたくない事をやらなければならないのは、嫌ですよね。 そんな気持ちは分かりますが、これを機に一度改めてみませんか。 何故なら、ドキュメントを書かない事はチームに「負債」を生むからです。 勤め人ならば少なからず一度でも、体験した事があると思います。 「どうして必要な過去の資料が無いんだ」って。 あるはずの歴史の一端がソースコードからしか分から
設計ドキュメント腐る問題、 Git管理で運用してみた 本当のところ 2023.12.5 真野隼記 ドキュメント管理を制する 陳腐化を防ぐための実践事例 Lunch LT
はじめに Domain Name System（DNS）はインターネットサービスを使用する上で欠かせない基幹サービスであり、DNSが関連するセキュリティインシデントへの対処は、健全なインターネットを維持するために重要です。本ブログでは、JPCERT/CCもメンバーとして参加しているFIRSTのDNS Abuse SIGが、2023年2月に公開したDNS Abuse Techniques Matrixについて、その日本語版をJPCERT/CCが主体となり作成および公開したので紹介します。 2023年2月、FIRSTのDNS Abuse SIGが公開したDNS Abuse Techniques Matrix - DNS Abuse Techniques Matrix https://www.first.org/global/sigs/dns/DNS-Abuse-Techniques-Matri
画像・PDF・TXT・メールなどの中身を読み取って検索できるようにするオープンソースのドキュメント整理ツール「Teedy」レビュー
Teedyはさまざまな種類のファイルの中身を読み取って検索できる状態にしてくれるドキュメント整理ツールです。受信したメールを自動で取り込む設定もできるとのことなので、実際にセルフホストして使い勝手を確かめてみました。 sismics/docs: Lightweight document management system packed with all the features you can expect from big expensive solutions https://github.com/sismics/docs TeedyのインストールにDockerを利用するので、下記のリンクから自分の環境に合った方法でDockerをインストールします。 Install Docker Engine | Docker Documentation https://docs.docker.com
［速報］GitHub、組織のコードやドキュメントを学習しカスタマイズやファインチューニングが可能な「Copilot Enterprise」発表。GitHub Universe 2023
［速報］GitHub、組織のコードやドキュメントを学習しカスタマイズやファインチューニングが可能な「Copilot Enterprise」発表。GitHub Universe 2023 GitHubの年次イベント「GitHub Universe 2023」が米サンフランシスコで開幕しました。 1日目の基調講演で、Copilotが組織のコードやドキュメントを学習することで、カスタマイズやファインチューニングが可能になる「GitHub Enterprise」が発表されました。 Copilot Enterpriseは、外部に公開されていない組織内のコードやドキュメント、プルリクエストなどを追加でCopilotに学習させることで、組織内のコードベースに基づいたCopilotによるコードの生成や、Copilot Chatでの質問に対する回答が可能になるというものです。 さらに言語モデルそのものを組織
git-schemlexとddl-makerを使ったDB migrationの紹介 / git-schemalex and ddl-maker migration #golangtokyo
はじめまして。損害保険ジャパン株式会社 DX推進部の眞方です。普段はリードエンジニアとして、新しいサービスのアーキテクチャ検討からローンチまでの作業や、新規技術を用いたアプリのプロトタイプ実装などを行なっています。 弊社では、LLM（Large Language Models）を活用したアプリケーションの開発を積極的に検討し、既に社内でいくつかのプロトタイプをローンチしています。 本記事では、その最も一般的？なユースケースの一つとも言えるRAG（Retrieval Augmented Generative）の構築において、ドキュメント検索精度の向上にどのように取り組んだ内容の概要を紹介させていただきます。実際の詳細な手法および結果については、別記事（実践編）で解説予定です。 はじめに RAGとは？ この記事を読まれている方の中にはご存知の方も多いでしょうが、RAGとはRetrieval A
困った時はドキュメント、どうもかわしんです。最近、諸事情で SQLite のドキュメントを読んでいます。 前回の記事 で紹介した通り SQLite を Rust で再実装しています。おかげさまで 300 を超える Github Star もいただき嬉しいです。 github.com SQLite は全ての仕様が ドキュメント にまとめられているので、そのドキュメントと本家の実装を読み比べながら実装しています。 SQLite を再実装する上で特に以下のドキュメントは役にたちます。これらだけで最小限の SQLite の実装は作れると思います。 Overview Documents > About SQLite いかに SQLite がすごいかを自慢しているドキュメント。使おうとしている人には安心を、再実装しようとする人には絶望を与えてくれます。 Programming Interfaces >
ドキュメント執筆にもGit、ビルド、テストで再利用性や整合性を実現する「Writerside」、JetBrainsがプレビューリリース
Kotlinなどの開発元として知られるJetBrainsは、テクニカルドキュメントのための一連のツールを統合したドキュメントオーサリングツール「Writerside」のプレビューリリースを発表しました。 ソフトウェア開発においては、テキストで記述されたソースコードをGitでバージョン管理し、ビルドによって複数のソースコードを1つのアプリケーションへとまとめ上げ、コンパイルし、テストをして本番環境へのデプロイによりアプリケーションを公開します。 そしてこのプロセス全体を、さまざまな機能を備えたツールチェンを用いて自動化することで、ソフトウェア開発の効率を高めています。 一方で、例えばアプリケーションのチュートリアル、SDKやAPIのリファレンスドキュメントなどのドキュメントの制作過程においては、複数のファイルをフォルダにまとめ、手作業で目次のページとリンクさせることや、ソースコードのサンプル
APIの開発は複雑でコストがかかる可能性があり、頻繁に更新されることからドキュメントを整備するのも難しい。APIの設計、開発、ドキュメントの整備、管理にまつわる課題と効率さの問題に対処するアプローチが、RESTful API Modeling Language（RAML：RESTful APIモデリング言語）だ。 RAMLコードを使えば、開発者はAPIの動作を説明する仕様を策定してからそのAPIをデプロイするまでのAPIライフサイクルを管理することができる。 RAMLとは RAMLは、RESTful APIを記述することを目的とするオープンソースの記述言語だ。2013年、米国のIT自動化および統合ベンダーであるMuleSoftを中心とする数社の企業によって作成されたRAMLはAPIの開発に大きな役割を果たしてきた。2018年、MuleSoftはSalesforceによって買収され、RAML
インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。さらに、ドキュメントの具体的な書き方と、フィードバックの収集について話します。前回はこちらから。 ドキュメントは「書き始める」ことが大事 岩瀬義昌氏：3章にいきます。時間的にあと15分ぐらいしゃべっても大丈夫かな？ 10分ちょっとしゃべれると思うので。（スライドが）あと70枚あるので、すごく速くいきますね（笑）。 ドラフトの執筆です。みなさんもドキュメントを書くじゃないですか。ちょっと胸に手を当てて（考えて）みると、ドキュメントを書く上で、一番難しいことは何だと思いますか？ （スライドを示して）書ける人は良いんですが、最初の人が1文字目を書き
はじめに COUNTERWORKSバックエンドエンジニアの伊藤です。 この記事ではAPIドキュメント分割の知見を紹介します。 弊社では OpenAPI を使用したスキーマ駆動開発を採用しています。 1ファイルで管理していたところ、25000行を超える行数となり管理コストが高くなっていました。 そこで分割作業を実施したのですが、どのような方針でどう対応したかを紹介します。 1ファイルで運用するデメリット そもそもどんなデメリットが発生していたのかを記載します。 全体の構造が把握しづらく、新規参画者への認知負荷が高い 行数が多すぎるため、RubyMine など IDE やエディタのパフォーマンスが落ちる 1ファイルの内部で複数の箇所を参照しているが、それぞれCommand fで該当部分を探す必要がある。そのため、見ているコードの箇所が頻繁に飛んで情報が追いづらい 実際にやったこと 方針 チーム
開発者向けのツールを展開する企業「JetBrains」がドキュメント作成のためのツール「Writerside」を早期アクセスで公開しました。早期アクセスの期間中はWritersideを無料で利用できるとのことなので、実際に使って試してみました。 Writerside - JetBrains が提供する新しい技術文書作成環境。 https://www.jetbrains.com/ja-jp/writerside/ Writersideの公式ページを開き、「ダウンロード」をクリックします。 今回はスタンドアロンツールとして利用するので、「ダウンロード」をクリックします。JetBrains IDEを利用している人はプラグイン形式で導入することも可能とのこと。 インストーラーがダウンロードされるのでダブルクリックして起動します。 「Next」をクリック。 インストールには空き容量が1.0GB必要で
インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。最後に、ドキュメントの品質測定について話します。前回はこちらから。 「優れたドキュメントとは何か」を定義する 岩瀬義昌氏：最後にもう1個だけ。今日は9章までしゃべりたかったので、これをあと5分でしゃべれればゴールですね。ドキュメントの品質測定について話していきます。 （スライドを示して）品質測定、このあたりのキーワードから、きっとエンジニアであれば1度は言われたことがあるんじゃないかという言葉はこれです。 「計測できないものは改善できない」という言葉があります。これはいろいろな引用元があるので（スライドの）後ろに画像を出していますが、計測した
ROUTE06では、GitLab Handbook*1を参考に、全社に関係する情報をハンドブックとして社内に公開しています。ハンドブックは2023年8月時点で383ページ*2あり、50人前後の組織規模の会社としては文章化に積極的なことが現れている数字だと思っています。 また、ハンドブックとは別に、プロジェクトごとのレポジトリでは技術選定や設計方針をADR*3で残していたり、参加したセミナーのレポートをGitHub Discussionsに書いていることからも、ROUTE06で働く人は文章を書くことが習慣になっていると感じます。 そんな中、ある日社内のSlackに一つの問いが投げかけられました。 ドキュメント文化というのは、たとえばマニュアルに書いてないから分からなかった・故になんらかの失敗が発生した場合、マニュアルに書いていなかったことが悪いみたいな考え方になるのでしょうか 社内のSlac
ドキュメントを書く仕事を探している
飲み会で「お前、次の転職どうするよ？」的な話をするときはいつも これまでは自分が一番下手くそなバンドメンバーになれる職場を意図的に探していたし、今の職場もその基準で選んだが、そろそろ俺の音楽をやりたい プログラミングそのものをドメインとした仕事をしたい ドキュメントやチュートリアルの整備をしたい。あわよくば今 blog.ojisan.io を書いていること自体が仕事になるようなことをしたい 的なことを言っている（はず、アルコールが入っているので記憶が定かでない）。 で、この最後の 「ドキュメントやチュートリアルの整備をしたい」というのはここ１年くらい言っている気がするのだが、そろそろ本当に動き出そうと思って最近ふわふわ考えていることを書いてみようと思う。そういう仕事をしている人の目に止まってくれると嬉しい。 どうしてドキュメントを書くような仕事をしたいのか いまこういったブログを運営してい
このブラウザーはサポートされなくなりました。 Microsoft Edge にアップグレードすると、最新の機能、セキュリティ更新プログラム、およびテクニカル サポートを利用できます。
Railsのプロジェクトがそこそこ大きくなり、ServiceやSerializerなどのカスタムレイヤーを追加してコードを細分化しているものの、レイヤーの役割やインターフェイスのルールが明確に決まっておらずふわふわとしていることを課題と感じていました。課題を解決するヒントを探すため、Railsの超巨大OSSプロジェクトであるGitLabの設計ドキュメントを読んでみました。 ガイドラインの必要性 まず初めにガイドラインの必要性が語られています。レイヤーの抽象化ができたとしても、それを正しく使えないと、あっという間にメンテナンスしにくいコードができてしまうということが説明されています。 例として、あるFinder（Finderはデータベースからデータを検索する抽象）の中で別のFinderを呼び出してはいけないということが挙げられています。もしそうしたなら、Finderにどんどんオプションが追加
設計書などドキュメント類は一切作りません！でもその代わりシステムの出来上がりは超速で価格も激安です。っていうベンダーの存在を知った
てとらα SI @TETRA_IT 設計書などドキュメント類は一切作りません！テスト結果もありません！でもその代わりシステムの出来上がりは超速で価格も激安です。っていう恐ろしい地方ベンダーの存在を知った。とにかく安く早くを求める地方企業や支社などの要望とマッチして管理不能なシステムが量産されてる 2024-05-28 09:25:50
最近、『エンジニアのためのドキュメントライティング』という本を読みました。 非常にためになる内容だったので、本書であがったいくつかのポイントを私なりにまとめてみました。 また、エンジニアにとってのドキュメントは種類が多く、それぞれのニーズとそれに合わせたフォーマットも違うため、 良いドキュメントとは何か？ を一概に述べることは難しいです。 個人的には、「ほぼ知識のない人が読んでも再現できる・解決できる」ということが大事なのではないかと思っています。 そこで、本記事ではドキュメントの範囲を少し絞って、想定される読者をエンジニア寄りに考えて書いています。ご了承ください。 目次 本記事では ドキュメントを作成する前 ドキュメントを作成する時 ドキュメントを作成した後 それぞれのタイミングにおけるポイントを挙げていきます。 📑 ドキュメント作成前のポイント フリクションログとは、あるユーザー1の
Google ドキュメントなどのワープロソフトでは、目立たないところに機能の宝庫が隠されています。そうした機能を使えば、大規模なドキュメントの草案をつくるのも、同僚と協力してそれを仕上げるのも簡単になります。 Google ドキュメント活用のヒントについては、以前の記事でもいくつかご紹介しましたが、この記事では、さらにもういくつかを紹介します。 1. 「マークダウン記述」で作業速度を高めるImage: Saikat BasuGoogle ドキュメントは、「マークダウン記法」をいくつかサポートしています。 そのおかげで、プレーンテキストの記号を使ってドキュメントの書式を簡単に整えて、読み書きしやすいものにできます。さらにより高度な書式への変換も可能です。 この機能を有効にすることで、書式を変えたい部分の前後に記号を入れることで、すばやく書式を変更できます。（「_」で囲めば斜字体、「~」で囲め
8/26(土) は湘南.pm #1でした。初開催おめでとうございます！主催のid:papix ありがとうございました!! そこで話したことを書いてみます。 意識高めの題ですが、まずはじめに私は翻訳は全くの素人です。英語が得意だから、英語ドキュメントを翻訳してみようと思ったわけではないです。私の人生、翻訳にご縁があるとは思っていませんでした。 Perlの公式ドキュメントを和訳するようなワーキンググループを一年運営した話をしてみたいと思います。 一年やってみて良かったと思いますし、技術コミュニティに貢献する手として、みなさんの頭の片隅にでも残ったら良いなと思って話します。 こばけんと言います！エンジニア組織開発責任者をしたり、開発生産性の可視化サービスを作ったり、技術コミュニティ活動したり、起業の準備をしています。 そして、この場をお借りして、お知らせをさせてください！ 2024年2月10日(
APIリファレンス（民間事業者向け） | デジタル認証アプリ | ドキュメント | デジタル庁 開発者サイト
レスポンスタイプ OpenID Connect の通り。 デジタル認証アプリサービスは、code（認可コード）のみをサポートする。 固定値codeを設定する。 " class="sc-iJuWdM sc-cBNeRQ gpkGbA dujygE">レスポンスタイプ OpenID Connect の通り。 デジタル認証アプリサービスは、code（認可コード）のみをサポートする。 固定値codeを設定する。
なんでお前らチケットに書いてあることをまともに読まないの？文盲なの？ なんで流し見しただけで読んだつもりになって、ばかみたいな質問してくるの？ なんでほぼ毎回「それチケットに書いてありますよ」って言われてるのに、質問を送信する前に自分でdescriptionに目を通さないの？ 人に質問する前にもう一回自分で読み直せよ、それが一番早いだろ。 送信ボタン押す前に再確認すればいいじゃん？なんでやんないの？ばかなの？ １００歩譲って、１０００歩譲って、１００００歩譲って、無駄な確認質問してくるのはまだいい。 ドキュメントに書かれてることを読まずに、ばかみたいな質問すらしてこないで、実装漏れすんのやめてくれよ。勝手な思い込みでヘンテコな実装すんのやめてくれよ。 なんかもう前提が欠けてるからむちゃくちゃ過ぎてレビューと修正にめちゃくちゃ時間かかってるじゃねえかよ。 ほぼ毎回レビューの結果もう最初に出て
はじめに 公式ドキュメントを読め！Qiitaを使うな このような発言はネットで時々見かけるような内容であり、ある程度プログラミングができるような方を中心に見かけるイメージのあるものです。 私はこの発言を見るたび思うことがあります。 Qiitaに投稿すべき内容を多くの人が間違っているからこのような発言が生まれている 今回は、「公式ドキュメントを読むべき理由」「Qiitaが適切な場合」「Qiitaに投稿すべき内容」について書いていきます。 公式ドキュメントを読め 「公式ドキュメントを読め」 これは私として気持ちがものすごくわかります。 公式ドキュメントにはだいたいの知りたい内容については書かれていますし、1次情報になるので情報が正確です。 QiitaやZennなどに解決方法がないかを時間を書けて調べるくらいならいきなり公式を見たほうが早く解決することも多いです。 その一方で「公式ドキュメントよ
はじめに 皆さんは、『公式ドキュメントを読んだほうがいいよ』とよく耳にしませんか？ そこで、『よし読むぞ！』と思っても、なかなかうまくいきませんよね💦 （そういう方々がこの記事を見に来てくれると思っている👀） 私も、公式ドキュメントを読むのが苦手で、まず最初に、Qiitaなどの技術系ブログに頼ってしまいますw そこで、なぜ自分が公式ドキュメントに苦手意識があり、どうしたらその抵抗をなくせるのかを考えたので、記録として記事にしたいと思います！🙆 ちなみに、公式ドキュメントとの思い出は、1年前ぐらいにDockerの公式ドキュメントで何が書いてあるか理解できず、15分くらいで読むことを諦めましたw ※自分がこの記事を通して公式ドキュメントが読めるようになるために努力した記事なので、公式ドキュメントを批判した記事ではないです！ 対象読者 公式ドキュメントを読むのが苦手な若手エンジニア 😅公
OpenAPI + Redoc, Docusaurus, Mermaidで始めるスキーマ・ドキュメント駆動開発
OpenAPI + Redoc, Docusaurus, Mermaidで始めるスキーマ・ドキュメント駆動開発 【この本について】 この本はOpenAPIを使ってドキュメントを作成する方法を学びます。 OpenAPIを使ってドキュメントを作成することで継続的な開発を行うことができ、 OpenAPI Generatorを使ってドキュメントと実装のズレをなくすことができます。 また、Docusaurusを使ってドキュメントを作成することで、 運用ドキュメントを簡単に公開することができます。 本書では以下の内容を取り扱っています。 - Docusarusでドキュメント環境を構築する - OpenAPI + Redocでドキュメントを作成する - OpenAPI Generatorで自動生成する - Prismでモックサーバーを導入する OpenAPIを使ってみたい人、社内の設計・運用ドキュメント
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
「ドキュメントの書き方」を体系的に学んだことがないエンジニアへ 書籍『エンジニアのためのドキュメントライティング』の概要
NHKスペシャル「ドキュメント エルサレム（前後編）」がすごかった
破綻したドキュメント管理、増え過ぎたプロダクトバックログ… 「Jira」「Confluence」などの活用失敗から学ぶツール運用のコツ
設計ドキュメント腐る問題、Git管理で運用してみた結果 | フューチャー技術ブログ
「マッチングアプリ」に疲れて「Googleドキュメント」に移行する人々が増加中 | もうスワイプする必要はない
ドキュメントを書かないことは「負債を生む」ということ - Qiita
20231206_設計ドキュメント腐る問題、Git管理で運用してみた本当のところ
DNSの不正使用手法をまとめた技術ドキュメントの公開 - JPCERT/CC Eyes
非同期開発体制を支えるドキュメント文化 / YAPC::Hiroshima 2024
RAGにおけるドキュメント検索精度向上について(概要編)
SQLite を再実装する時に役にたつドキュメント - kawasin73のブログ
RESTful APIの設計、開発、ドキュメント管理を手助けする「RAML」とは
ユーザーはドキュメントを「読みにくるけれど読んでいない」 “流し読み”しやすいドキュメント作成のポイント
25000行超えのAPIドキュメントを分割した話
コード開発と同じようにしてドキュメントが作成できるJetBrains製「Writerside」を使ってみた
優れたドキュメントは目的にかなっている “読む目的”を達成させるために書き手が意識したい「2つの品質」
ドキュメント文化を支える不文律 - ROUTE06 Tech Blog
Microsoft 365 Copilot ドキュメント
Railsの設計に迷ったのでGitLabの設計ドキュメントを読んでみた | DevelopersIO
ドキュメントをいい具合に残そうの会 - Qiita
【特集】 困ったときのWindows 11のリセット、どのファイルが保持されるのか？ドキュメントやIME辞書、Steamなど細かく調べてみた
Google ドキュメント上級者が使いこなしている「8つの裏技」 | ライフハッカー・ジャパン
「Word」ドキュメントがぐちゃぐちゃになる要因、既定の貼り付けオプションが変更へ／Windows版で実施
ドキュメントでプログラミング言語に貢献する - Blog::kobaken
EMから物申す。低能プログラマども、ドキュメントをちゃんと読め。
公式ドキュメントを読め。Qiitaを開くな。 - Qiita
なぜ僕は公式ドキュメントを読むのが苦手なのか - Qiita