ドキュメントを書かないことは「負債を生む」ということ - Qiita
本記事の要約 ドキュメントを書かない事は、企業やチームの「負債」になる ドキュメントを書かない事は、自身の学びや振り返りの「機会損失」になる そういう文化が根付く前に、負の連鎖を断ち切ろう！ はじめに 世の中のプロジェクトには、ドキュメントが足りていない、と感じています。 でも残念な事に、ドキュメントをどうしても書きたい人は「ほとんどいない」と思います。 その一方で「ドキュメントを書いた方が良い」という事は、 何となく分かっている人も多いと思います。 やりたくない事をやらなければならないのは、嫌ですよね。 そんな気持ちは分かりますが、これを機に一度改めてみませんか。 何故なら、ドキュメントを書かない事はチームに「負債」を生むからです。 勤め人ならば少なからず一度でも、体験した事があると思います。 「どうして必要な過去の資料が無いんだ」って。 あるはずの歴史の一端がソースコードからしか分から
網羅的なPRDやDesign Docを書かなくなった - kosui
2024/06/12 16:16 結論を追記 2024/06/12 20:29 より記事の内容を分かりやすく理解頂くため、タイトルを「PRDやDesign Docを書かなくなった」から変更 2024/06/13 20:39 結論にフロー情報・ストック情報に関する意見を追記 結論 この記事では、「様々な観点を考慮して網羅的にドキュメントを書いて、それを関係者にレビューしてもらう」のではなく、関係者と同期的に対話しながら、観点や選択肢やそのトレードオフを洗い出すことで、少ない手数でより良い答えが見つけられると主張する。 ただし、対話のために必要なドキュメントは事前に書いておくべきだし、対話した結果はドキュメントに残すことが望ましい。そして、そのドキュメントのフォーマットはPRDやDesign Doc以外でも良い。例えば、ADRはアーキテクチャに関する議論の過程と結果を述べる上で必要十分なフォー
100人以上の資料を読んで見つけた伝わりやすい成果報告書の書き方 - CARTA TECH BLOG
TL;DR 自身の成果をアピールするために、1)Before/After、2)自分の寄与度、3)数字的インパクトを過不足なく伝えることが重要 説明の冒頭では、課題と解法の全体感と成果を述べ、詳細は後に肉付けすると伝わりやすい 課題を伝える際は"誰から見た課題か"を明確にする。課題は解法の前提であるためブレないように はじめに 技術広報のしゅーぞーです。この記事では、過去100人分程度の成果報告書を読み、気付いた "自分の成果をわかりやすく伝える書き方"をまとめています。 仕事をしていると自身の成果を的確に伝える機会は数多くありますよね。 評価期、転職面接、昇格面談など 評価者に自分の成果をどう分かりやすく伝えるか は自分のキャリアを伸ばす上でとても大事なスキルです。 しかし、自分の頑張りや成果を上手く言語化し、相手に正しく理解してもらうのは簡単ではありません。 特に、経験の浅い若手にとって
変更履歴を記録する
Version 1.1.0 # Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] ### Added - v1.1 Brazilian Portuguese translation. - v1.1 German Translation - v1.1 Spanish translation. - v1.1 Italian
25000行超えのAPIドキュメントを分割した話
はじめに COUNTERWORKSバックエンドエンジニアの伊藤です。 この記事ではAPIドキュメント分割の知見を紹介します。 弊社では OpenAPI を使用したスキーマ駆動開発を採用しています。 1ファイルで管理していたところ、25000行を超える行数となり管理コストが高くなっていました。 そこで分割作業を実施したのですが、どのような方針でどう対応したかを紹介します。 1ファイルで運用するデメリット そもそもどんなデメリットが発生していたのかを記載します。 全体の構造が把握しづらく、新規参画者への認知負荷が高い 行数が多すぎるため、RubyMine など IDE やエディタのパフォーマンスが落ちる 1ファイルの内部で複数の箇所を参照しているが、それぞれCommand fで該当部分を探す必要がある。そのため、見ているコードの箇所が頻繁に飛んで情報が追いづらい 実際にやったこと 方針 チーム
画像・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
tblsのViewPoint機能を用いたGithub Actions上でのDBドキュメントの自動生成 - Safie Engineers' Blog!
この記事はSafie Engineers' Blog! Advent Calendar 2日目の記事です。 セーフィー株式会社でテックリードをやっております鈴木敦志です。 セーフィーはクラウドカメラのSaaSを提供しており、現在22万台程度のデバイスに対してカメラ映像をクラウドから視聴する機能を提供しています。 それに加えエンタープライズ向けの権限管理機能や社内向けの販売管理ツールなど複数のサービスを運営しており、各サービスでMySQLのDBを共有しているためDBのテーブル数が肥大化し構造がわかりにくくなり、新機能開発の妨げとなっていました。 本稿ではデータベースのドキュメンテーションツールである tbls を導入し、DBスキーマ管理ツール skeema、ドキュメント生成ツール mkdocs、Github Actionsなどと組み合わせてスキーマ管理からドキュメント生成までをやっていきます
1年かけてAnewsのドキュメントを改善した話
エンジニアリングユニットの酒井といいます。 昨年の9月に入社し、Anewsの開発に従事しつつ時々SREっぽいこともしています。 今回は、自分が入社当初から改善したいなぁと考えていたAnewsのドキュメントについて、これまでやってきた取り組みについてお話しできればと思います。 取り組みを始めたきっかけそもそも自分は組織開発において、ドキュメントが重要だという認識がありました。それはこれまでの経験則によるところもありますし、『Googleのソフトウェアエンジニアリング』中で以下のような言及があり、重要性を再認識したというのもあります。 10.2 何故ドキュメンテーションが必要なのか p220: ドキュメンテーションは長期的に見ると決定的に重要であり、決定的に重要なコードにとっては特に、組織がスケールするのに伴い途方もない恩恵をもたらす。 テストを書くことは普通になりつつありますが、ドキュメント
ADR を1年間書いてみた感想 - 一休.com Developers Blog
宿泊開発チームでエンジニアをしている @kosuke1012 です。チームで ADR を書き始めて1年くらい経ったので、その感想を書いてみたいと思います。 この記事は 一休.comのカレンダー | Advent Calendar 2023 - Qiita の13日目の記事です。 ADRとは アーキテクチャ・ディシジョン・レコードの略で、アーキテクチャに関する意思決定を軽量なテキストドキュメントで記録していくものです。 出典はこちらで、 Documenting Architecture Decisions わかりやすい和訳は以下の記事が、 アーキテクチャ決定レコードの概要 | Cloud アーキテクチャ センター | Google Cloud アーキテクチャ・デシジョン・レコードの勧め | 豆蔵デベロッパーサイト アーキテクチャの「なぜ？」を記録する！ADRってなんぞや？ #設計 -
エンジニアが開発しやすい環境作り - Qiita
はじめに 自分は現在、システム開発会社にて執行役員としてプロジェクトマネジメントやコンサルをしています。 今までのプロジェクトから得た経験を元に、エンジニアが開発しやすい環境作りについて、自分なりにまとめていきます。 対象者 エンジニアチームのモチベーションを上げたい人 エンジニアチームにとって開発しやすい環境作りを知りたい人 お断り 今回紹介するのは自分が実践してきた一例であり、必ずしも正解というわけではありません 「こうしなさい」ではなく「こうするとより良くなるかも」といったモチベで書いています GitHubで開発を進める前提 目次 ドキュメント整備 issueの作成 開発環境の整備 コードレビュー プロジェクトの開発進捗の管理について ドキュメント整備 まずはじめに、エンジニアが開発に入る際に必ず見る「README」の書き方を説明していきます。 自分がREADMEを書く時は「プロジェ
zod-to-openapiで、既存のAPI実装にOpenAPIドキュメントを後付けする | Memory ice cubes
昔々あるところに、既存のWeb APIの実装がありました。 それなりに実装を進めた後に、天の声が言いました。「OpenAPIのドキュメントを公開したい」と。 さて、あなたならどうする？っていうニッチな問いに対する一つの答えとして。 ルーターごと乗り換える？ たとえば今回でいうと、元のAPIはCloudflare Workersにデプロイされてた。 ので、たとえばhonoとかitty-routerとか、OpenAPIのドキュメント生成ができるエコシステムが整ってるルーターに乗り換えてしまうという手がある。 https://github.com/honojs/middleware/tree/main/packages/zod-openapi hono好きなあなたに https://github.com/cloudflare/itty-router-openapi/ itty-router好きな
社内ドキュメントはなぜ更新されないのか？情報の鮮度を最小限の運用負荷で維持する「イミュータブルドキュメントモデル」のススメ - KAKEHASHI Tech Blog
はじめに こんにちは。カケハシの各プロダクトを支えるプラットフォームシステムの開発チームでテックリードを担当しているkosui(@kosui_me)です。 プロダクト開発の世界では、明瞭な社内向けドキュメントを書くための方法が数多く提案されてきました。読者の中には、製品要求を明瞭にするためにPRD (Product Requirements Document、製品要求仕様書) を書き、プロジェクトの背景から全体の設計やその代案について明瞭にするためにDesign Docsを書き、アーキテクチャに関する意思決定の記録を明瞭にするためにADR(Architecture Decision Record) を書いてきた方も数多くいらっしゃると思います。 しかし、どんな素晴らしいドキュメントも、何故か更新されなくなります。新メンバーへのオンボーディングのためにインフラ構成図を検索したあなたが見つけた
ドキュメントを書く仕事を探している
飲み会で「お前、次の転職どうするよ？」的な話をするときはいつも これまでは自分が一番下手くそなバンドメンバーになれる職場を意図的に探していたし、今の職場もその基準で選んだが、そろそろ俺の音楽をやりたい プログラミングそのものをドメインとした仕事をしたい ドキュメントやチュートリアルの整備をしたい。あわよくば今 blog.ojisan.io を書いていること自体が仕事になるようなことをしたい 的なことを言っている（はず、アルコールが入っているので記憶が定かでない）。 で、この最後の 「ドキュメントやチュートリアルの整備をしたい」というのはここ１年くらい言っている気がするのだが、そろそろ本当に動き出そうと思って最近ふわふわ考えていることを書いてみようと思う。そういう仕事をしている人の目に止まってくれると嬉しい。 どうしてドキュメントを書くような仕事をしたいのか いまこういったブログを運営してい
軽量で自分のローカル環境上に構築するメモサイトを探しているなら！「memos」 - ソフトウェア開発者のための OSS、まとめてみました！
概要 皆さまはメモを取りたいときやタスクを管理したい、アイデアを何かにまとめたいといった場合、どのようなものに頼っていますでしょうか？ 非デジタルであればノートだったりメモ帳を使用しているかもしれませんし、デジタルであればメモアプリだったりテキストエディタを利用、もしくはクラウド管理されているアプリを利用してるかと思います。 今回はデジタルで利用するメモアプリの話題について取り上げていきたいと考えていますが、もしデジタルでメモを取っている方はどのようなアプリや Web サイトを利用されていますでしょうか？ 有名どころで、メモやタスク管理、ドキュメント管理、データベースなど、仕事で使う様々なツールが 1 つにまとまっているアプリ「Notion」を利用されている方が多いのではないかと考えています。 www.notion.so 私自身も普段からこちらの「Notion」を積極的に利用させていただい
ドキュメントの限界 - orangeitems’s diary
インフラの環境構築を行ったときに、はい、環境です、と接続情報だけ顧客に提供したところで、そのまま受け取ってくれることはない。 ドキュメントはないんですか？。 何を作ったかを示すドキュメントとセットで初めて、プロにお金を払って仕事をしてもらった気持ちになる。今でも、ドキュメントを残せ、ドキュメントがないと今どうなっているかがわからなくなる、常に更新して最新にしよう、そんな掛け声は健在である。 このドキュメント、年々複雑さが増していると思う。というのも、IT関連のソフトウェアにしろクラウドにしろ、機能は増えるばかりだからだ。かつ、設定自体は年々洗練されており、デフォルト値で動くことも多い。たくさんの設定項目があるが、設定するのはほんの一部分である。 ドキュメントに何を残すべきか。設定値全てをドキュメントに書き込もうものなら莫大な量になる。一方で変更したものは少ししかない。このギャップが激しくな
無料の研修・プレゼン資料がどっさり freeeのテックブログが“神まとめ”になっていた
昨今、さまざまなIT企業が社内の研修資料などを学習コンテンツとして公開している。例えばセガやMIXI、リクルート、サイボウズなどがコンテンツを公開しており、よくSNSで「神資料」などと話題になる。実際、ITmedia NEWSでもたびたび取り上げており、人気が出やすい記事となっている。企業側にとっても、IT人材の関心を集める有効な手段の一つだろう。 こういった資料が公開されるのは、企業のテックブログ（技術ブログ・開発ブログとも呼ぶ）であることが多い。従って、記者は記事のネタを求めて日々さまざまな企業のテックブログをウォッチしている。そんな中で、あるSaaS企業のテックブログが目を引く取り組みをしているのを見つけた。 その企業とは、クラウド型会計・人事サービスを手掛けるfreeeだ。freeeは、自社のテックブログ「freee Developers Hub」で、2021年以降に社員が登壇した
エンジニアのためのドキュメントライティング - ぱたへね
エンジニアのためのドキュメントライティング読みました。 最近の仕事の悩みに対して、方向性を示してくれた良い本でした。 www.amazon.co.jp 自分のチーム内にドキュメントの文化が無い人にお勧めします。 全体のざっくりした感想だと、この手の本にありがちな小言っぽいことは書いてなく、作って意味のあるドキュメントはどうあるべきかを書いてあります。仕事のドキュメントで悩んでいる人には、具体的な取り組みのアイデアがいっぱい見つかるでしょう。 背景 うちの会社は転職者が多く、開発への考え方がバラバラ。当然、ドキュメントに対する考え方もバラバラで必要なドキュメントがなかなか揃わない。今の仕事は各部署からの寄せ集めチームでもあり、ドキュメントのテンプレートみたいなものもない。 世代間の格差も結構ある。ベテラン勢はドキュメントは印刷され保管される前提であり、表示にバージョン、日付、部署、作成者など
読み手を意識したテクニカルドキュメントを書くために /「エンジニアのためのドキュメントライティング」を読んだ - kakakakakku blog
2023年3月に出版された「エンジニアのためのドキュメントライティング」を読んだ．原著は Docs for Developers で，翻訳を担当された @iwashi86 さんに本書を送っていただいた．ありがとうございます❗️そして出版おめでとうございます🎉 本書は今まで書いてきたテクニカルドキュメントに対して "できてなかったな〜" という気付きを与えてくれるイイ本でした📖 読みながら感じたことを大きく分類すると以下2点！印象に残ったところを中心にまとめようと思う． テクニカルドキュメントの重要さを改めて認識できた👌 テクニカルライティングという仕事（ポジション）に興味を持った👀 ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング 作者:ジャレッド・バーティ,ザッカリー・サラ・コーライセン,ジェン・ランボーン,デービッド・ヌーニェス,ハイディ・
良いドキュメントを書きたくなる本を読んだらドキュメンタリアンになりたくなった - じゃあ、おうちで学べる
ドキュメンタリアンとは、役職に関係なく、ソフトウェア業界でドキュメントとコミュニケーションに関心を持つ人のことです。 www.writethedocs.org はじめに これは主に『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の書評です。私はSreakeにてSREという役職についています。SREはサービス概要、アーキテクチャの解説や図、各種構成図、各種手順書、ポストモーテム、ポリシー、SLA(SLO) … その他の様々な場面でドキュメントを書く必要があります。しかし、ドキュメントは価値が見えにくく時間と労力がかかり品質担保の面で重要度がとても高いのにその場での価値が見えにくいので浸透しにくいです。そのため、エンジニアとしてモチベーションが保ちづらいです。2021年 State of DevOps 2021 にもドキュメントに関する言及があり今後、
terraform-docsでドキュメントの自動生成 - とことんDevOps | 日本仮想化技術のDevOps技術情報メディア
IaCでインフラを管理していると、構築手順書が不要になります。構築手順がコードで表現されているからです。では、一切のドキュメントが不要かというと、そんなことはありません。設定値の説明などは必要になるので、使い方のドキュメントは必要になります。 かんたんDevOpsではIaCツールとしてTerraformを使っているんですが、terraform-docsというツールを使うと、そこそこのドキュメントがツールによって生成できることがわかりました。っということで、さっそく使ってみます。 terraform-docs??? terraform-docs.io github.com Terraformモジュールからドキュメントを生成するツールです。使っているモジュールがどのバージョンに依存しているのか、Input/Outputに渡すべき値なんかはわざわざ手で修正していると面倒ですし、修正漏れの原因にな
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
