ドキュメントを書かないことは「負債を生む」ということ - Qiita
本記事の要約 ドキュメントを書かない事は、企業やチームの「負債」になる ドキュメントを書かない事は、自身の学びや振り返りの「機会損失」になる そういう文化が根付く前に、負の連鎖を断ち切ろう！ はじめに 世の中のプロジェクトには、ドキュメントが足りていない、と感じています。 でも残念な事に、ドキュメントをどうしても書きたい人は「ほとんどいない」と思います。 その一方で「ドキュメントを書いた方が良い」という事は、 何となく分かっている人も多いと思います。 やりたくない事をやらなければならないのは、嫌ですよね。 そんな気持ちは分かりますが、これを機に一度改めてみませんか。 何故なら、ドキュメントを書かない事はチームに「負債」を生むからです。 勤め人ならば少なからず一度でも、体験した事があると思います。 「どうして必要な過去の資料が無いんだ」って。 あるはずの歴史の一端がソースコードからしか分から
1年かけてAnewsのドキュメントを改善した話
エンジニアリングユニットの酒井といいます。 昨年の9月に入社し、Anewsの開発に従事しつつ時々SREっぽいこともしています。 今回は、自分が入社当初から改善したいなぁと考えていたAnewsのドキュメントについて、これまでやってきた取り組みについてお話しできればと思います。 取り組みを始めたきっかけそもそも自分は組織開発において、ドキュメントが重要だという認識がありました。それはこれまでの経験則によるところもありますし、『Googleのソフトウェアエンジニアリング』中で以下のような言及があり、重要性を再認識したというのもあります。 10.2 何故ドキュメンテーションが必要なのか p220: ドキュメンテーションは長期的に見ると決定的に重要であり、決定的に重要なコードにとっては特に、組織がスケールするのに伴い途方もない恩恵をもたらす。 テストを書くことは普通になりつつありますが、ドキュメント
エンジニアリングの時間を生み出すドキュメンテーション術 - エムスリーテックブログ
【データ基盤チーム ブログリレー 3日目】 こんにちは、エンジニアリンググループの石塚です。 趣味は筋トレです。好きなトレーニングはレッグカールです。今年2023年の1月に第一子が爆誕し、毎日子供の笑顔に癒されております。一方であまり言い訳にはしたくはないですが、事実自分自身の自由に使える時間は少なくなったなと感じております。そんな中でもトレーニングの時間は作りたいので、24時間ジムに契約して妻と娘が寝ている早朝の時間にウホウホトレーニングをしている今日この頃であります。時間のありがたみをとても感じるようになりました。 これは仕事でも同様かと思います。有限な時間の中でタスクを取捨選択して価値ある成果を上げていく事が仕事では求められます。ドキュメンテーションはその価値ある成果につながる時間を増やす一助になるかもしれません。 この記事では、ドキュメンテーションの必要性について言語化します。改め
良いドキュメントを書きたくなる本を読んだらドキュメンタリアンになりたくなった - じゃあ、おうちで学べる
ドキュメンタリアンとは、役職に関係なく、ソフトウェア業界でドキュメントとコミュニケーションに関心を持つ人のことです。 www.writethedocs.org はじめに これは主に『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の書評です。私はSreakeにてSREという役職についています。SREはサービス概要、アーキテクチャの解説や図、各種構成図、各種手順書、ポストモーテム、ポリシー、SLA(SLO) … その他の様々な場面でドキュメントを書く必要があります。しかし、ドキュメントは価値が見えにくく時間と労力がかかり品質担保の面で重要度がとても高いのにその場での価値が見えにくいので浸透しにくいです。そのため、エンジニアとしてモチベーションが保ちづらいです。2021年 State of DevOps 2021 にもドキュメントに関する言及があり今後、
CHANGELOG の書き方 - 角待ちは対空
VS Code の拡張作っている際に CHANGELOG.md が自動生成され、書き方はKeep a Changelogに従えと書かれていたので紹介する。 ここに書かれていることは絶対ではなくただ提案しているだけである。意見がある人は話し合おうという温度感っぽいので、納得いかない場合は issue 立てると良いと思う。 僕自身はなんでもよくてある程度型が欲しかっただけなのでこれからはこれに従って書いていこうと思う。ただまぁ Semantic Versioning もそうだけどちゃんと従おうとすると以上にだるくなってくるので雰囲気従うくらいだと思う。 CHANGELOG の原則 機械的に生成するのではなく人間の手で書く 各セクションへのリンクが容易にできる 1つのバージョンごとに1つのサブセクションを作る リリースは新しいものが上に来るようにする 日付のフォーマットは YYYY-MM-DD
技術文書の書き方
howto-tech-docs.md 技術文書の書き方 このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。
仕様書の参考例と、こんな内容を仕様書に最低書くといいというお話｜田辺めぐみ
よく、仕様書を書いていなくて、書いてみたいけど、具体的な仕様書がネット上に落ちてなくってこまってるって相談を受けるので 「仕様書の記載内容のイメージ」を作りました！ ※前提として「現在仕様書を書いていない、自社開発のMVP検証前後のフェーズのスタートアップ向け」に書いています。PMが仕様書、エンジニアがDesign Docを書く分担です。 ついでに、システム開発の基礎である「システム開発のV字モデルをベースにした設計書の紹介」も含めてまとめてみましたー！ 大規模開発に使われたり、古くからあるフレームワークなので、スタートアップの方だと、システム開発のV字モデルの概念やそれにあわせた成果物を知らない人が多いけど、「要件定義書」と「設計書」を全てドキュメント化するとどうなるかを理解した上で、「仕様書」として情報を削る方が、考慮漏れ防止やエンジニアがやっている設計内容の理解につながるので、全体を
エンジニアのための、いますぐ使える文章校正テクニック - ICS MEDIA
ウェブ制作や開発の仕事で文章を扱う機会は多いはず。書き手は不自然に思っていない文章でも、読み手は違和感をもっていることがあります。文章校正テクニックを覚えるだけでおかしな表現は少なくなり、読みやすい文章を書けるようになります。 本記事では、ICS MEDIAで実践している文章校正の一例を紹介します。 レベル1、基本的な校正ルールを使う いろんな場面で使える基本的な文章校正テクニックから紹介します。 テクノロジー系の名詞は正しく記載しているか テクノロジー系の名詞を間違って使うと、「本当に技術に詳しいの？」と読者からの信頼度が下がります。名詞は大文字小文字、スペース有無含めて正確に記述しましょう。 Github → GitHub（Hは大文字） Javascript → JavaScript（Sは大文字） After Effect → After Effects（複数形の「s」を忘れてはいけな
ドキュメントが更新されない問題 - Konifar's ZATSU
むかし、この国が深い森におおわれ、そこに太古からの神々がすんでいた頃から語り尽くされているドキュメントが更新されない問題について雑に書く。 実態が変わったのにドキュメントが更新されない問題はいつどの時代も絶えない。これにいちいち憤りを感じるのは不幸になるだけなので、何かしら対処を考えておかねばならない。パッと思いつくのは次のようなものだろうか。 使う 使わないから更新もされなくなる。定期的に使われるように設計して、そもそも使わない場合は消した方がいい いっそ参照回数が少ないドキュメントは自動でアーカイブしちゃうみたいな硬派なスタイルの方がいいのかも 詳細に書きすぎない 細かいところを書きすぎると保守できない。骨組みだけ大事にして、細かいところはフロー情報として分けて書くのがよい 管理者を置く ちゃんと更新されるようロールを作る。属人化しないようにロールを引き継ぐ設計も必要 個人的にはあんま
ソフトウェアドキュメント作法 - maru source
こんにちは丸山@h13i32maruです。つい先日、devchat.fmというポッドキャストに出演して、「ドキュメント」というお題について話しました。なぜこんなニッチなお題について話したかというと、Ubie Discoveryに入社して5ヶ月の間にいくつか*1まとまったソフトウェアドキュメントを書いたので、自分の中でホットな話題だったからです。 #devchatfm 33回目は、Ubie DiscoveryのSWE @h13i32maru にドキュメントを書くことで得られるメリットや、ポイント・工夫などを聞きました！ #33 チームの生産性を上げるドキュメントのすすめ with@h13i32maruhttps://t.co/TrmZd13D91— 久保 恒太 / Ubie CEO (@quvo_ubie) 2021年8月12日 これらのドキュメントは個人的にわりと良く書けたと思ってますし、
社内のドキュメンテーションの取り組みと、Kitenのご紹介 - Pepabo Tech Portal
はじめに 技術部の @june29 と申します。最近の趣味は「お散歩」で、よく晴れた休日には妻といっしょに2時間くらい歩き回ったりしています。この記事では、わたしが2020年から力を入れて取り組んでいる社内におけるドキュメンテーションの活動の一部を紹介したいと思います。 問題意識 もともと、ペパボで働く人々には「書く」という行為が定着しています。現在利用中のサービスを見渡してみると、GitHub、Slack、Google Docs、Scrapbox、Notionなどがあり、常に積極的な読み書きが行われています。 しかし、ドキュメンテーションという観点から見て、すべてが理想的にうまくいっているとは言えない状況であるとも思っていました。具体的には、下記のような課題があると感じていました。 書く場所が何種類もあり、どこになにが書かれているかがわかりにくい 場所ごとにアクセス制限が行われており、ど
質の高い技術文書を書く方法 - As a Futurist...
大学や大学院で論文の書き方を鍛え上げた人たちには遠く遠く及ばないが、僕の様なはぐれもの1でも最近は Amazon 社内で文書の質が高いと評価してもらえるまでにはなった。Software Engineer として、コードでのアウトプットはもちろん大事だけど、文書のアウトプット(およびそれによって得られた実際のアウトプット)は同じだけ重要である2。今回は自分が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。 そもそも文書とは？ 英語だと document。ここで指す(技術)文書とは、人間が読む文体で書かれた技術に関連する情報、といったものだ。具体的に言うと以下の様なものを想定している: 新しいプロジェクトの骨子を説明する資料 会議の叩き台となる 1 枚ペラ 本番環境に変更を加えるにあたっての包括的な情報や具体
Amazonの従業員が学ぶ伝わる文章構成の極意｜Sangmin Ahn
こんにちは、Choimirai School のサンミンです。 【主要なアップデート】 （2023.10.01）ベゾス氏がパワポを禁止した理由を語った動画を追加 （2020.05.11）Blitzscaling、ビル・ゲイツのコメントと英語版リンクを追加 （2020.05.11）知的生産の技術に関するコメントを追加 0 はじめに ▲アマゾンの社内プレゼンテーションで、パワーポイントの使用が禁止されているのは、かなり有名な話。 会議では、冒頭のおよそ15～20分間、参加者全員にドキュメントを読むための時間があてられる。ドキュメントは６ページと長い場合も多く静まったミーティングルームで参加者が黙々とドキュメントを読む雰囲気はかなり緊張感が漂っている。
Google、技術文書を公開するようなWebに向けたテンプレート集「Docsy」を公開 | OSDN Magazine
Googleは7月10日、オープンソースプロジェクトのドキュメント公開に向けたWebサイトテーマ「Docsy」を公開した。ドキュメントを公開するサイトを簡単に立ち上げて運用できるという。 Docsyは技術文書を公開するようなWebサイトのためのテーマで、Webサイト構築のためのフレームワーク「Hugo」をベースとする。Googleは2000以上のオープンソースプロジェクトを抱えており、ドキュメンテーション作成と公開のためのツールが必要だったことから構築したとのこと。技術文書向けのテンプレートとガイドを備えており、すでにKubeflow、Knative、Agonesなどのプロジェクトで利用しているという。 ナビゲーション、サイト構造などの機能を提供するほか、多言語にも対応する。ページの追加、ドキュメンテーションの構造化、コミュニティからの貢献などについてもガイドを提供するという。 Docsy
「という」と「こと」を減らすだけで、文章はぐっと読みやすくなる｜Ryo Yoshitake | THE GUILD
と思っている話です。もはやタイトルでぜんぶ言ってしまった。 せっかくなのでもう少し続けます。 2020/05/03追記：第二弾？書きました この本がまだ初稿になる前、共著者のみなさんと執筆真っ最中の頃に何度か打ち合わせがあったのですが、そこで「書籍的な文章を書き慣れてない人って、"という"と"こと/もの"を多用しがちなので、この2つを抑えるだけでも文章がシュッとするんですよ」とお話したら思ったより反応があったので、これは需要があるんじゃないかと感じたのがきっかけです。 ここから先は具体例を交えて解説していきます。 さすがに他人様のテキストを使うのは気が引けるので自分が書いた記事を例に挙げます。……でも自分はこのテクニックを使うようにしているので、該当する記事がなかなかないんですよねぇ……と思ったらあった！ （よりによってこれか……せっかくなので皆さんスタァライトを観ましょう！） 記事中では
AWSの各種サービスやSDKのドキュメントがオープンソースとしてGitHubに公開。誰でもコントリビュートや再利用が可能に
AWSの各種サービスやSDKのドキュメントがオープンソースとしてGitHubに公開。誰でもコントリビュートや再利用が可能に Today we are adding over 138 additional developer and user guides to the organization, and we are looking forward to receiving your requests. You can fix bugs, improve code samples (or submit new ones), add detail, and rewrite sentences and paragraphs in the interest of accuracy or clarity. 今日、私たちは138以上のデベロッパーガイドとユーザーガイドを追加し、みなさんの要望を心待ち
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
エンジニアのためのドキュメントライティング / Docs for Developers
無料で使える日本語文章のAI校正Shodo（ショドー）。タイポ、変換ミス、誤字脱字チェックに
技術文書アンチパターン集
プログラミング言語 Ruby リファレンスマニュアル