この記事は？ 株式会社ログラスでクラウドインフラエンジニアをしている中井 (@elmodev09) です。 エンジニアとして働ていると、技術選定の調査結果をまとめたり、Design Docを書く等、ドキュメントを書く機会が多いのではないでしょうか？ ドキュメントは、不必要なディスカッションを減らすための非常に強力なツールです。 特に、抽象度が高いタスクにおいては、ドキュメントをうまく活用することで議論のポイントを明確化し、効率化を図ることができます。 個人的な話になりますが、これまでに書いたドキュメントについて、「分かりやすい」「読みやすい」と言っていただけることが多いです。 （もちろん、毎回そうではなく、分かりにくい場合もありますが） 私は口頭で全てを明確に説明するのが得意な方ではないため、思考を整理してドキュメントにまとめることで、なんとかエンジニアとしての業務をこなしています。 今回

「コードを書くのは好きだけどドキュメントは苦手」 「ドキュメントはつい後回しにしてしまう」 エンジニアの皆さん、そんな覚えはありませんか？ 本書は、日本語ドキュメントのスペシャリストであるテクニカルライターの著者が、エンジニアが「いつ」「何のドキュメントを」「どうやって」書けばよいのかを、イチから解説します。 先生役の著者と生徒役をキャラクターにし、全編にわたってイラストを豊富に掲載。 はじめてドキュメントを書くエンジニア、またはこれまで自己流で書いてきたエンジニアが、一度読めば一生使える知識満載です。 装丁画と挿絵は、カケヒジュンさんが手がけます。 ＜基礎編＞ Chapter１　良いドキュメントを効率良く書くために Chapter２　ドキュメントの読み方を理解する Chapter３　読み手とテーマを選定する Chapter４　テーマを分解する Chapter５　ドキュメントの骨組みを組む

72ページ / A5サイズ / 電子版はPDF（フルカラー） / 紙の本は表紙カラー、本文モノクロ 技術書典16（2023年5月25日～6月9日）の新刊「読み手につたわる文章 - テクニカルライティング」です。 「書籍版＋PDF版」は紙の本と電子書籍（PDF）がセットになっています。 「PDF版」は名前のとおり、PDFをダウンロードできます。紙の本はついてこないので注意してください。 この本は技術書典オンラインマーケットでも購入できます。 https://techbookfest.org/product/3t8AGqtB65jsPtPhx6m5fr 「ダウンロードカード用」は、既に紙の書籍をお持ちの方向けのファイルです。紙の書籍を購入された方は、あとがきの後ろにダウンロード用のパスワードが記載されています。ダウンロード後、あとがきに記載されているパスワードでZIPファイルを解凍してください

絶賛成長期にあるだろう若手エンジニアは、どういう流れで自身の成長を促したら良いのだろうか、とふと思いつつ口頭で説明してみたけどよくわからんくなったので整理してみたいお気持ちです。 当ブログではアウトプットの効用みたいなものは書いてきましたが、インプットそのものについてはお初なので、自身を振り返る良い機会にもなりそうです。 はじめに これは私が二十数年間、プログラマー・インフラ・SRE といったエンジニアとして通ってきた中で、どのようにインプットをしてきたかを整理してみるチラ裏です。 自分は一般(?)と比べれば少々特殊な経歴で、情報学を学んだことも、新卒研修を受けたことも、IT系資格も、転職したこともない…… ほぼ独学による野良エンジニアとして生息してきましたので、あまり参考にはならないかもしれません。 それでも一応長く生き抜いてきたエンジニアの経験として、インターネットに数多くある参考例の

日々のタスクに忙殺されていると、ついつい既存コードを流し読みして、ざっと動くコードを書いてしまいたくなります。 一発でうまく動けば短期的にはいいのですが、長期的にはコードの理解が追いつかなったり、一発でうまく動かなかった場合にかえって時間がかかってしまいます。 VSCode の拡張機能である Code Tour を使うと、コード上にメモを残しながら読み進めることができるので、既存のコードを読む際に便利です。 Code Tour とは VSCode の拡張機能で、コード上にメモを残しつつ、そのメモをたどることができるツールです。 使い方 ツアーを始める コマンドパレットから「Code Tour: Record Tour」を選択すると、ツアーの記録モードになります。 ツアーの名前 どのソースに紐づけるか（紐付けなし、ブランチ、タグ） を選択すると、リポジトリ直下に .tours/${指定したツ

「読む人のことを考える」 これだけ。 僕は、ドキュメントを読むのが苦手。すぐに混乱する。 ひとつの段落が長いと混乱する。正確に書いてくれているんだろうけど、書き手目線で細かくばーって書いてあって、読み手がそこから自分の目的の情報を探し出さないといけない状態だと混乱する。 あと、ページの階層が深かったり、リンクでジャンプしまくったり、用語がぶれていたり、文章が複数の意味に捉えられる書き方になっていたりすると、混乱する。 そんな風に、たぶん僕は他の人よりもドキュメントを読むのが苦手なんだと思う。 だから、自分が読んでも混乱しないようなドキュメントを書くと、まわりの人にとっても分かりやすいドキュメントになっているみたい。それで「分かりやすいね」って、ほめてもらって嬉しい。ドキュメントを読むのが苦手で役に立った！ どんなことに気をつけてるかな？と考えてみる。 そのドキュメントの目的が分からないと混

おそらく 2023 年に Zenn で出す最後の記事になるかと思います。 タイトルの通り、2023 年に読んだ本の中で、特に素晴らしかったものをご紹介します。 とはいえあまり今年は技術書を読んだ印象がなく… というのも、特定の xx(例えば Next.js、Ktor)といった部類に関しては公式のドキュメントを読むことがほとんどになり、書籍に求めるのは公式ドキュメントに書かれていない何かや誰かの経験・ノウハウになったからだと思います。 この記事を書くにあたって今年読んだ本を振り返ってみても、やはり十数冊程度(それでも月に 1 冊は読んでた)のでインプット：アウトプットの割合的には良いバランスではないかと思っています。 ただ、先に述べた通り公式ドキュメントに書かれていないなにかを売っている本というのはどれも本当の意味で価値があるものであり、皆さんにも本当に意味のある情報にお金を使っていただける

このブログは、 IVRy 紅白Advent Calendar 2023の白組・17日目の記事です。 白組16日目は PdM佐瀬さん「IVRyなら上流からUX/UIデザイン業務が実践できます！」でした。明日はIVRyのVPoE近藤さんの「IVRyにおける開発生産性へのアプローチ～SPACEフレームワークの視点から～」についての記事が出ます。乞うご期待。 この記事について タイトル通り、2023年に提案されて改善した事を発表するのですが、裏返すと「そんなこともできてなかったのか」と見える内容もあるかもしれません。ネガティブに受け取られる可能性もあるかもしれませんが、IVRyのオープンな社風や、常に改善と変革に前向きな姿勢をアピールするためにも、この記事を執筆することにしました。 なお、課題を発見・解決しながら会社を大きくしていきたいエンジニアの皆さんは、ぜひブログ一番下のIVRyの採用情報から

最終更新日: 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. ご挨拶 初投稿となります

自己紹介 こんにちは。名刺メーカーDevグループの伊藤惇です。 私は2022年4月にSansanに新卒として入社して、現在に至るまで名刺データの作成および印刷発注をするサービスの開発に携わっています。 名刺メーカーDevグループでは、偶然タイミングが重なったこともあり、私が入社してからこれまでの間に5人が育児休暇を取得しました。 そうした中で感じた育休に対する考え方の変化を振り返りたいと思います。 なお、本記事はSansan Advent Calendar 2023の14日目の記事です。 名刺メーカー育休スケジュール 名刺メーカーDevグループの規模感 チームの人数やプロダクトのフェーズによっても育休のインパクトが変わってくるので、私が所属する名刺メーカーDevグループの規模感について補足しておきます。 チーム人数 後述するAさん、Bさん、Cさんの育休取得時は約15人ほどのチームでした。そ

設計ドキュメント腐る問題、 Git管理で運用してみた 本当のところ 2023.12.5 真野隼記 ドキュメント管理を制する 陳腐化を防ぐための実践事例 Lunch LT

はじめに AI搭載コードエディターCursorが話題なので自分にとって使いやすいのか実験してみました。 まだまだCursorの実験途中ではありますが、CursorProをサブスクしてたった３日でgpt-4に332回聞いてました。 Cursorはプロンプトの会話から現在のコードにDiffで提案してくれたり、エラーを解決してくれたり本当に便利で最高なのですが、頼り過ぎも良くないなと反省することもあったので、やったこと全部と感想をシェアしていきたいと思います。 やったこととしては、Cursorのチャットに質問しながら予備知識のないChatVRMというオープンソースのチャットアプリケーションの追加実装をしました。わりと簡単に実装できたこととうまくできなかったことがあるので例を挙げて紹介していきます。 Cursorとは Cursor(カーソル)とは、VScodeをフォークして作られたOpenAIのg

浅原 昭生 @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… 2023-11-19 20:00:00

はじめに こんにちは。カケハシの各プロダクトを支えるプラットフォームシステムの開発チームでテックリードを担当しているkosui(@kosui_me)です。 プロダクト開発の世界では、明瞭な社内向けドキュメントを書くための方法が数多く提案されてきました。読者の中には、製品要求を明瞭にするためにPRD (Product Requirements Document、製品要求仕様書) を書き、プロジェクトの背景から全体の設計やその代案について明瞭にするためにDesign Docsを書き、アーキテクチャに関する意思決定の記録を明瞭にするためにADR(Architecture Decision Record) を書いてきた方も数多くいらっしゃると思います。 しかし、どんな素晴らしいドキュメントも、何故か更新されなくなります。新メンバーへのオンボーディングのためにインフラ構成図を検索したあなたが見つけた

ずっと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の出現回数は変わってないのでマッチしない

インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く　エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。最後に、ドキュメントの品質測定について話します。前回はこちらから。 「優れたドキュメントとは何か」を定義する岩瀬義昌氏：最後にもう1個だけ。今日は9章までしゃべりたかったので、これをあと5分でしゃべれればゴールですね。ドキュメントの品質測定について話していきます。 （スライドを示して）品質測定、このあたりのキーワードから、きっとエンジニアであれば1度は言われたことがあるんじゃないかという言葉はこれです。 「計測できないものは改善できない」という言葉があります。これはいろいろな引用元があるので（スライドの）後ろに画像を出していますが、計測したい

インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く　エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。まずは、本書籍の概要について話します。 本セッションの対象者と、セッションのゴール岩瀬義昌氏：ご紹介いただきました、岩瀬と申します。よろしくお願いします。『ユーザーの問題解決とプロダクトの成功を導く　エンジニアのためのドキュメントライティング』は、もともと『Docs for Developers: An Engineer’s Field Guide to Technical Writing』という洋書だったんですが、その翻訳をして、今回この機会をいただいています。 余談ですが、APC（株式会社エーピーコミュニケーションズ）さんが「カプセルトイ

セキュリティを盾に一点突破。どうもかわしんです。最近 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 SoftwareやTrelloなどを中心としたPMが経験してきたプロダクト管理ツールの失敗や改善を語る「本当に使いこなせてる？プロダクト管理ツールの失敗&改善PMトーク【開発PM勉強会 vol.20】」。ここで株式会社ビズリーチの菊池氏が登壇。ドキュメント管理とプロダクトバックログの失敗から学ぶツール運用のコツについて紹介します。 菊池氏の自己紹介菊池信太郎氏（以下、菊池）：ビズリーチの菊池から、10分枠で話をします。今日のテーマは「失敗から学ぶドキュメントとチケット運用のコツ」ということで、今まで経験したところで「こういうアンチパターンがあったよ」「こういう改善をしたよ」というようなところをお話しできればと思っています。 自己紹介を軽くすると、（私は）2018年からビズリーチで働いています。ビズリーチサービスを作っていて、プラットフォーム開発部の部長をしています。また、2019

ドキュメントを書くときに、みなさんが気をつけていることは何でしょう？　情報の正確さや文章表現など、さまざまなことに気をつけていると思います。これらに加え、ドキュメントを書く上では、「読み手の理解」が重要です。今回は、2023年3月に発行された『ユーザーの問題解決とプロダクトの成功を導く　エンジニアのため…