読み手につたわる文章 - テクニカルライティング - mochikoAsTech - BOOTH
72ページ / A5サイズ / 電子版はPDF（フルカラー） / 紙の本は表紙カラー、本文モノクロ 技術書典16（2023年5月25日～6月9日）の新刊「読み手につたわる文章 - テクニカルライティング」です。 「書籍版＋PDF版」はBOOTH倉庫での入荷作業が完了し次第、買えるようになります。 「入荷お知らせメールを受け取る」を押しておくと、入荷されたときにメールが届きます。 「PDF版」は名前のとおり、PDFをダウンロードできます。紙の本はついてこないので注意してください。 なおPDF版は技術書典オンラインマーケットでも購入できます。 https://techbookfest.org/product/3t8AGqtB65jsPtPhx6m5fr 「ダウンロードカード用」は、既に紙の書籍をお持ちの方向けのファイルです。紙の書籍を購入された方は、あとがきの後ろにダウンロード用のパスワードが
インプットのすゝめ | 外道父の匠
絶賛成長期にあるだろう若手エンジニアは、どういう流れで自身の成長を促したら良いのだろうか、とふと思いつつ口頭で説明してみたけどよくわからんくなったので整理してみたいお気持ちです。 当ブログではアウトプットの効用みたいなものは書いてきましたが、インプットそのものについてはお初なので、自身を振り返る良い機会にもなりそうです。 はじめに これは私が二十数年間、プログラマー・インフラ・SRE といったエンジニアとして通ってきた中で、どのようにインプットをしてきたかを整理してみるチラ裏です。 自分は一般(?)と比べれば少々特殊な経歴で、情報学を学んだことも、新卒研修を受けたことも、IT系資格も、転職したこともない…… ほぼ独学による野良エンジニアとして生息してきましたので、あまり参考にはならないかもしれません。 それでも一応長く生き抜いてきたエンジニアの経験として、インターネットに数多くある参考例の
Code Tour を使ってじっくり確実にコードを読む
日々のタスクに忙殺されていると、ついつい既存コードを流し読みして、ざっと動くコードを書いてしまいたくなります。 一発でうまく動けば短期的にはいいのですが、長期的にはコードの理解が追いつかなったり、一発でうまく動かなかった場合にかえって時間がかかってしまいます。 VSCode の拡張機能である Code Tour を使うと、コード上にメモを残しながら読み進めることができるので、既存のコードを読む際に便利です。 Code Tour とは VSCode の拡張機能で、コード上にメモを残しつつ、そのメモをたどることができるツールです。 使い方 ツアーを始める コマンドパレットから「Code Tour: Record Tour」を選択すると、ツアーの記録モードになります。 ツアーの名前 どのソースに紐づけるか（紐付けなし、ブランチ、タグ） を選択すると、リポジトリ直下に .tours/${指定したツ
チーム用のドキュメントを書くときに考えてるたったひとつのこと｜cba
「読む人のことを考える」 これだけ。 僕は、ドキュメントを読むのが苦手。すぐに混乱する。 ひとつの段落が長いと混乱する。正確に書いてくれているんだろうけど、書き手目線で細かくばーって書いてあって、読み手がそこから自分の目的の情報を探し出さないといけない状態だと混乱する。 あと、ページの階層が深かったり、リンクでジャンプしまくったり、用語がぶれていたり、文章が複数の意味に捉えられる書き方になっていたりすると、混乱する。 そんな風に、たぶん僕は他の人よりもドキュメントを読むのが苦手なんだと思う。 だから、自分が読んでも混乱しないようなドキュメントを書くと、まわりの人にとっても分かりやすいドキュメントになっているみたい。それで「分かりやすいね」って、ほめてもらって嬉しい。ドキュメントを読むのが苦手で役に立った！ どんなことに気をつけてるかな？と考えてみる。 そのドキュメントの目的が分からないと混
2023年に読んでよかった技術書
おそらく 2023 年に Zenn で出す最後の記事になるかと思います。 タイトルの通り、2023 年に読んだ本の中で、特に素晴らしかったものをご紹介します。 とはいえあまり今年は技術書を読んだ印象がなく… というのも、特定の xx(例えば Next.js、Ktor)といった部類に関しては公式のドキュメントを読むことがほとんどになり、書籍に求めるのは公式ドキュメントに書かれていない何かや誰かの経験・ノウハウになったからだと思います。 この記事を書くにあたって今年読んだ本を振り返ってみても、やはり十数冊程度(それでも月に 1 冊は読んでた)のでインプット：アウトプットの割合的には良いバランスではないかと思っています。 ただ、先に述べた通り公式ドキュメントに書かれていないなにかを売っている本というのはどれも本当の意味で価値があるものであり、皆さんにも本当に意味のある情報にお金を使っていただける
2023年・新しく入ったメンバーの提案で開発チームが良くなったこと5選
このブログは、 IVRy 紅白Advent Calendar 2023の白組・17日目の記事です。 白組16日目は PdM佐瀬さん「IVRyなら上流からUX/UIデザイン業務が実践できます！」でした。明日はIVRyのVPoE近藤さんの「IVRyにおける開発生産性へのアプローチ～SPACEフレームワークの視点から～」についての記事が出ます。乞うご期待。 この記事について タイトル通り、2023年に提案されて改善した事を発表するのですが、裏返すと「そんなこともできてなかったのか」と見える内容もあるかもしれません。ネガティブに受け取られる可能性もあるかもしれませんが、IVRyのオープンな社風や、常に改善と変革に前向きな姿勢をアピールするためにも、この記事を執筆することにしました。 なお、課題を発見・解決しながら会社を大きくしていきたいエンジニアの皆さんは、ぜひブログ一番下のIVRyの採用情報から
社内技術ドキュメンテーションを科学する - スタディサプリ Product Team Blog
最終更新日: 2024年05月07日(火) 1. ご挨拶 2. 本記事執筆のモチベーション 3. ワークショップを通じて得たフィードバック 3-1. Pains -過去抱えた/現在進行形で抱えている辛み- 3-2. Approaches/Solutions -Pains を解消するために取った方策や導き出した解決策- 3-2-1. えいやで場所を決め打ちしてしまう(e.g., GitHub Wiki + Google docs しか使わない) 3-2-2. 個人的に、2023/12/05時点で〜みたいな書き方を心がけている 3-3. Tips -効果的な手法- 4. オーディエンスからの反響 4-1. 気づきや学び・NEXT ACTIONS 4-2. プレゼンター(@hayat01sh1da)へのフィードバック 4-3. Slack での反応 5. おわりに 1. ご挨拶 初投稿となります
入社して1年半の間に先輩が5人育休に入った話 - Sansan Tech Blog
自己紹介 こんにちは。名刺メーカーDevグループの伊藤惇です。 私は2022年4月にSansanに新卒として入社して、現在に至るまで名刺データの作成および印刷発注をするサービスの開発に携わっています。 名刺メーカーDevグループでは、偶然タイミングが重なったこともあり、私が入社してからこれまでの間に5人が育児休暇を取得しました。 そうした中で感じた育休に対する考え方の変化を振り返りたいと思います。 なお、本記事はSansan Advent Calendar 2023の14日目の記事です。 名刺メーカー育休スケジュール 名刺メーカーDevグループの規模感 チームの人数やプロダクトのフェーズによっても育休のインパクトが変わってくるので、私が所属する名刺メーカーDevグループの規模感について補足しておきます。 チーム人数 後述するAさん、Bさん、Cさんの育休取得時は約15人ほどのチームでした。そ
Cursor Proを３日間で300回も使い倒してみた所感
はじめに AI搭載コードエディターCursorが話題なので自分にとって使いやすいのか実験してみました。 まだまだCursorの実験途中ではありますが、CursorProをサブスクしてたった３日でgpt-4に332回聞いてました。 Cursorはプロンプトの会話から現在のコードにDiffで提案してくれたり、エラーを解決してくれたり本当に便利で最高なのですが、頼り過ぎも良くないなと反省することもあったので、やったこと全部と感想をシェアしていきたいと思います。 やったこととしては、Cursorのチャットに質問しながら予備知識のないChatVRMというオープンソースのチャットアプリケーションの追加実装をしました。わりと簡単に実装できたこととうまくできなかったことがあるので例を挙げて紹介していきます。 Cursorとは Cursor(カーソル)とは、VScodeをフォークして作られたOpenAIのg
「どうか旅の最後までおつきあいください。」NHKのドキュメンタリー『ニッポンおもひで探訪』がじわじわと話題に
浅原 昭生＠C103日曜東5ホール「ピ」40b @HEYANEKO 当方が制作協力したNHKの番組、 「ドキュメント20min. ニッポンおもひで探訪 ～北信濃 神々が集う里で～」が 次の日曜日（11/19）の深夜（24:00～）、NHK総合でオンエアされます。 nhk.jp/p/ts/YN5YRJ9KP… よろしかったら、チェックしてみてください。 #ドキュメント20min #ニッポンおもひで探訪 2023-11-16 07:02:34 ＮＨＫ長野放送局🍎 @nhk_nagano 俳優・ #宍戸開 さんが #飯山市 を訪れ 地域の伝統に触れる旅 🍂 ＃ドキュメント20min. どうかどうかどうか･･･ 旅の最後まで おつきあいください🙏 総合 📺 今夜 🌙 午前0:00～ （ 19日(日)深夜 🌙 ） 「ニッポンおもひで探訪」 nhk.jp/p/ts/YN5YRJ9KP… 2
社内ドキュメントはなぜ更新されないのか？情報の鮮度を最小限の運用負荷で維持する「イミュータブルドキュメントモデル」のススメ - KAKEHASHI Tech Blog
はじめに こんにちは。カケハシの各プロダクトを支えるプラットフォームシステムの開発チームでテックリードを担当しているkosui(@kosui_me)です。 プロダクト開発の世界では、明瞭な社内向けドキュメントを書くための方法が数多く提案されてきました。読者の中には、製品要求を明瞭にするためにPRD (Product Requirements Document、製品要求仕様書) を書き、プロジェクトの背景から全体の設計やその代案について明瞭にするためにDesign Docsを書き、アーキテクチャに関する意思決定の記録を明瞭にするためにADR(Architecture Decision Record) を書いてきた方も数多くいらっしゃると思います。 しかし、どんな素晴らしいドキュメントも、何故か更新されなくなります。新メンバーへのオンボーディングのためにインフラ構成図を検索したあなたが見つけた
git logの内容を検索する-Sと-Gの違い - $shibayu36->blog;
ずっとgit logの内容を検索するときに-Sオプションを使っていたが、実は近いオプションに-Gオプションもあり、探したい内容によっては使い分けないとダメということを初めて知った... 詳しくはhttps://git-scm.com/docs/git-logの-Sと-Gのドキュメントを見てほしい。簡単にまとめると -Sは指定した文字列の出現回数が変わるdiffがあるcommitを検索する -Gは指定した正規表現がマッチする文字列がdiffにあるcommitを検索する ドキュメントの事例部分が結構わかりやすくて、以下のようなdiffがあった場合 + return frotz(nitfol, two->ptr, 1, 0); ... - hit = frotz(nitfol, mf2.ptr, 1, 0); -S frotzで検索をかけると、frontsの出現回数は変わってないのでマッチしない
優れたドキュメントは目的にかなっている “読む目的”を達成させるために書き手が意識したい「2つの品質」
インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。最後に、ドキュメントの品質測定について話します。前回はこちらから。 「優れたドキュメントとは何か」を定義する 岩瀬義昌氏：最後にもう1個だけ。今日は9章までしゃべりたかったので、これをあと5分でしゃべれればゴールですね。ドキュメントの品質測定について話していきます。 （スライドを示して）品質測定、このあたりのキーワードから、きっとエンジニアであれば1度は言われたことがあるんじゃないかという言葉はこれです。 「計測できないものは改善できない」という言葉があります。これはいろいろな引用元があるので（スライドの）後ろに画像を出していますが、計測した
「ドキュメントの書き方」を体系的に学んだことがないエンジニアへ 書籍『エンジニアのためのドキュメントライティング』の概要
インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。まずは、本書籍の概要について話します。 本セッションの対象者と、セッションのゴール 岩瀬義昌氏：ご紹介いただきました、岩瀬と申します。よろしくお願いします。『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』は、もともと『Docs for Developers: An Engineer’s Field Guide to Technical Writing』という洋書だったんですが、その翻訳をして、今回この機会をいただいています。 余談ですが、APC（株式会社エーピーコミュニケーションズ）さんが「カプセルト
Rust で SQLite を再実装している - kawasin73のブログ
セキュリティを盾に一点突破。どうもかわしんです。最近 Rust で SQLite を実装してます。 以前の記事で HTTP Parser を Rust で実装しようとしたものの、すでに実装されていたので断念しましたが、いい題材を見つけました。SQLite です。開発中のリポジトリはこれです。 github.com 今の時点では、Read Only で1つの WHERE 句を持った SELECT 文しか処理できないですが、以下の機能を実装しています。 sqlite3 で生成された database ファイルの読み取り (cursor.rs, btree.rs, record.rs) SQL 文の解析 (token.rs, parser.rs) テーブルとインデックスのメタデータのパース (schema.rs) 動的なファイルの読み込み (pager.rs) SQL クエリとスキーマ情報を元に
破綻したドキュメント管理、増え過ぎたプロダクトバックログ… 「Jira」「Confluence」などの活用失敗から学ぶツール運用のコツ
Jira SoftwareやTrelloなどを中心としたPMが経験してきたプロダクト管理ツールの失敗や改善を語る「本当に使いこなせてる？プロダクト管理ツールの失敗&改善PMトーク【開発PM勉強会 vol.20】」。ここで株式会社ビズリーチの菊池氏が登壇。ドキュメント管理とプロダクトバックログの失敗から学ぶツール運用のコツについて紹介します。 菊池氏の自己紹介 菊池信太郎氏（以下、菊池）：ビズリーチの菊池から、10分枠で話をします。今日のテーマは「失敗から学ぶドキュメントとチケット運用のコツ」ということで、今まで経験したところで「こういうアンチパターンがあったよ」「こういう改善をしたよ」というようなところをお話しできればと思っています。 自己紹介を軽くすると、（私は）2018年からビズリーチで働いています。ビズリーチサービスを作っていて、プラットフォーム開発部の部長をしています。また、201
良いドキュメントを書きたくなる本を読んだらドキュメンタリアンになりたくなった - じゃあ、おうちで学べる
ドキュメンタリアンとは、役職に関係なく、ソフトウェア業界でドキュメントとコミュニケーションに関心を持つ人のことです。 www.writethedocs.org はじめに これは主に『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の書評です。私はSreakeにてSREという役職についています。SREはサービス概要、アーキテクチャの解説や図、各種構成図、各種手順書、ポストモーテム、ポリシー、SLA(SLO) … その他の様々な場面でドキュメントを書く必要があります。しかし、ドキュメントは価値が見えにくく時間と労力がかかり品質担保の面で重要度がとても高いのにその場での価値が見えにくいので浸透しにくいです。そのため、エンジニアとしてモチベーションが保ちづらいです。2021年 State of DevOps 2021 にもドキュメントに関する言及があり今後、
本質的ではないが重要なNotionドキュメンテーション作成テクニック
はじめに みなさんはNotionを使っていますか？私は仕事でもプライベートでも活用しています。Ubieという私が所属している会社ではドキュメントは全面的にNotionを使用しており、仕事の細かなドキュメントや議事録から、外部に公開するためのカルチャーガイド(UPP)まで、様々なところでNotionが使われています。 ドキュメンテーションの本質は、とにかく文書を書くことです。その上で、それをどうやって人に読んでもらうか、意図を理解してもらうか、ということが次に来ます。読まれる場所に文書があったからといって、それが乱雑に言いたいことを書きなぐった文書だったり、短編小説レベルの長文であれば、それを人が上から下まで完璧に読んで理解してくれると期待することは酷でしょう。伝えたい内容が簡潔に記してあり、かつそれが読者の目を惹いてかつ読みやすい形になっていて、初めて伝わる文書であると私は思います。 そこ
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
20231206_設計ドキュメント腐る問題、Git管理で運用してみた本当のところ
読み手を理解してより良いドキュメントを書こう / Write better documents by understanding your audience
