本記事の要約 ドキュメントを書かない事は、企業やチームの「負債」になる ドキュメントを書かない事は、自身の学びや振り返りの「機会損失」になる そういう文化が根付く前に、負の連鎖を断ち切ろう！ はじめに 世の中のプロジェクトには、ドキュメントが足りていない、と感じています。 でも残念な事に、ドキュメントをどうしても書きたい人は「ほとんどいない」と思います。 その一方で「ドキュメントを書いた方が良い」という事は、 何となく分かっている人も多いと思います。 やりたくない事をやらなければならないのは、嫌ですよね。 そんな気持ちは分かりますが、これを機に一度改めてみませんか。 何故なら、ドキュメントを書かない事はチームに「負債」を生むからです。 勤め人ならば少なからず一度でも、体験した事があると思います。 「どうして必要な過去の資料が無いんだ」って。 あるはずの歴史の一端がソースコードからしか分から

dummy GA 新しいURLに転送しています… https://stockmark-tech.hatenablog.com/entry/2023/12/14/170000...

【データ基盤チーム ブログリレー 3日目】 こんにちは、エンジニアリンググループの石塚です。 趣味は筋トレです。好きなトレーニングはレッグカールです。今年2023年の1月に第一子が爆誕し、毎日子供の笑顔に癒されております。一方であまり言い訳にはしたくはないですが、事実自分自身の自由に使える時間は少なくなったなと感じております。そんな中でもトレーニングの時間は作りたいので、24時間ジムに契約して妻と娘が寝ている早朝の時間にウホウホトレーニングをしている今日この頃であります。時間のありがたみをとても感じるようになりました。 これは仕事でも同様かと思います。有限な時間の中でタスクを取捨選択して価値ある成果を上げていく事が仕事では求められます。ドキュメンテーションはその価値ある成果につながる時間を増やす一助になるかもしれません。 この記事では、ドキュメンテーションの必要性について言語化します。改め

2023年3月17日に開催されたイベント「エンジニアのためのドキュメントライティング - Forkwell Library #19」の登壇資料です。 イベントURL：https://forkwell.connpass.com/event/276576

ドキュメンタリアンとは、役職に関係なく、ソフトウェア業界でドキュメントとコミュニケーションに関心を持つ人のことです。 www.writethedocs.org はじめに これは主に『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の書評です。私はSreakeにてSREという役職についています。SREはサービス概要、アーキテクチャの解説や図、各種構成図、各種手順書、ポストモーテム、ポリシー、SLA(SLO) … その他の様々な場面でドキュメントを書く必要があります。しかし、ドキュメントは価値が見えにくく時間と労力がかかり品質担保の面で重要度がとても高いのにその場での価値が見えにくいので浸透しにくいです。そのため、エンジニアとしてモチベーションが保ちづらいです。2021年 State of DevOps 2021 にもドキュメントに関する言及があり今後、

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字モデルの概念やそれにあわせた成果物を知らない人が多いけど、「要件定義書」と「設計書」を全てドキュメント化するとどうなるかを理解した上で、「仕様書」として情報を削る方が、考慮漏れ防止やエンジニアがやっている設計内容の理解につながるので、全体を

無料で使えるAI校正ツール - Shodo（ショドー） Shodoが運営する無料で使えるAI文章校正ツールです！ 通常版よりも機能が制限されています。 AIによる執筆機能やより高度な校正機能はShodoアプリ（無料から）をご利用ください。

ウェブ制作や開発の仕事で文章を扱う機会は多いはず。書き手は不自然に思っていない文章でも、読み手は違和感をもっていることがあります。文章校正テクニックを覚えるだけでおかしな表現は少なくなり、読みやすい文章を書けるようになります。 本記事では、ICS MEDIAで実践している文章校正の一例を紹介します。 レベル1、基本的な校正ルールを使う いろんな場面で使える基本的な文章校正テクニックから紹介します。 テクノロジー系の名詞は正しく記載しているか テクノロジー系の名詞を間違って使うと、「本当に技術に詳しいの？」と読者からの信頼度が下がります。名詞は大文字小文字、スペース有無含めて正確に記述しましょう。 Github → GitHub（Hは大文字） Javascript → JavaScript（Sは大文字） After Effect → After Effects（複数形の「s」を忘れてはいけな

むかし、この国が深い森におおわれ、そこに太古からの神々がすんでいた頃から語り尽くされているドキュメントが更新されない問題について雑に書く。 実態が変わったのにドキュメントが更新されない問題はいつどの時代も絶えない。これにいちいち憤りを感じるのは不幸になるだけなので、何かしら対処を考えておかねばならない。パッと思いつくのは次のようなものだろうか。 使う 使わないから更新もされなくなる。定期的に使われるように設計して、そもそも使わない場合は消した方がいい いっそ参照回数が少ないドキュメントは自動でアーカイブしちゃうみたいな硬派なスタイルの方がいいのかも 詳細に書きすぎない 細かいところを書きすぎると保守できない。骨組みだけ大事にして、細かいところはフロー情報として分けて書くのがよい 管理者を置く ちゃんと更新されるようロールを作る。属人化しないようにロールを引き継ぐ設計も必要 個人的にはあんま

こんにちは丸山@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日 これらのドキュメントは個人的にわりと良く書けたと思ってますし、

はじめに 技術部の @june29 と申します。最近の趣味は「お散歩」で、よく晴れた休日には妻といっしょに2時間くらい歩き回ったりしています。この記事では、わたしが2020年から力を入れて取り組んでいる社内におけるドキュメンテーションの活動の一部を紹介したいと思います。 問題意識 もともと、ペパボで働く人々には「書く」という行為が定着しています。現在利用中のサービスを見渡してみると、GitHub、Slack、Google Docs、Scrapbox、Notionなどがあり、常に積極的な読み書きが行われています。 しかし、ドキュメンテーションという観点から見て、すべてが理想的にうまくいっているとは言えない状況であるとも思っていました。具体的には、下記のような課題があると感じていました。 書く場所が何種類もあり、どこになにが書かれているかがわかりにくい 場所ごとにアクセス制限が行われており、ど

大学や大学院で論文の書き方を鍛え上げた人たちには遠く遠く及ばないが、僕の様なはぐれもの1でも最近は Amazon 社内で文書の質が高いと評価してもらえるまでにはなった。Software Engineer として、コードでのアウトプットはもちろん大事だけど、文書のアウトプット(およびそれによって得られた実際のアウトプット)は同じだけ重要である2。今回は自分が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。 そもそも文書とは？ 英語だと document。ここで指す(技術)文書とは、人間が読む文体で書かれた技術に関連する情報、といったものだ。具体的に言うと以下の様なものを想定している: 新しいプロジェクトの骨子を説明する資料 会議の叩き台となる 1 枚ペラ 本番環境に変更を加えるにあたっての包括的な情報や具体

こんにちは、Choimirai School のサンミンです。 【主要なアップデート】 （2023.10.01）ベゾス氏がパワポを禁止した理由を語った動画を追加 （2020.05.11）Blitzscaling、ビル・ゲイツのコメントと英語版リンクを追加 （2020.05.11）知的生産の技術に関するコメントを追加 0  はじめに ▲アマゾンの社内プレゼンテーションで、パワーポイントの使用が禁止されているのは、かなり有名な話。 会議では、冒頭のおよそ15～20分間、参加者全員にドキュメントを読むための時間があてられる。ドキュメントは６ページと長い場合も多く静まったミーティングルームで参加者が黙々とドキュメントを読む雰囲気はかなり緊張感が漂っている。

Googleは7月10日、オープンソースプロジェクトのドキュメント公開に向けたWebサイトテーマ「Docsy」を公開した。ドキュメントを公開するサイトを簡単に立ち上げて運用できるという。 Docsyは技術文書を公開するようなWebサイトのためのテーマで、Webサイト構築のためのフレームワーク「Hugo」をベースとする。Googleは2000以上のオープンソースプロジェクトを抱えており、ドキュメンテーション作成と公開のためのツールが必要だったことから構築したとのこと。技術文書向けのテンプレートとガイドを備えており、すでにKubeflow、Knative、Agonesなどのプロジェクトで利用しているという。 ナビゲーション、サイト構造などの機能を提供するほか、多言語にも対応する。ページの追加、ドキュメンテーションの構造化、コミュニティからの貢献などについてもガイドを提供するという。 Docsy

You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert

と思っている話です。もはやタイトルでぜんぶ言ってしまった。 せっかくなのでもう少し続けます。 2020/05/03追記：第二弾？書きました この本がまだ初稿になる前、共著者のみなさんと執筆真っ最中の頃に何度か打ち合わせがあったのですが、そこで「書籍的な文章を書き慣れてない人って、"という"と"こと/もの"を多用しがちなので、この2つを抑えるだけでも文章がシュッとするんですよ」とお話したら思ったより反応があったので、これは需要があるんじゃないかと感じたのがきっかけです。 ここから先は具体例を交えて解説していきます。 さすがに他人様のテキストを使うのは気が引けるので自分が書いた記事を例に挙げます。……でも自分はこのテクニックを使うようにしているので、該当する記事がなかなかないんですよねぇ……と思ったらあった！ （よりによってこれか……せっかくなので皆さんスタァライトを観ましょう！） 記事中では

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以上のデベロッパーガイドとユーザーガイドを追加し、みなさんの要望を心待ち