howto-tech-docs.md 技術文書の書き方 このメモは、私(@ymmt2005)が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。
こんにちは丸山@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日 これらのドキュメントは個人的にわりと良く書けたと思ってますし、
以下の文章は、コリイ・ドクトロウの「Google reneged on the monopolistic bargain」という記事を翻訳したものである。 Pluralistic 驚くべきことに、かつてAltavistaやYahooをふっと飛ばし、魔法の検索ツールで世界を驚かせたGoogleが、突如クソの山になってしまった。 Googleの検索結果はひどいものだ。ページの上部はスパム、詐欺、広告だらけだ。始末に終えないのは、その広告も詐欺だらけなのだ。時には、資金力のある敵対者がGoogleを出し抜いて大金を稼ごうと大掛かりな詐欺が試みることもある。 https://www.nbcnews.com/tech/tech-news/phone-numbers-airlines-listed-google-directed-scammers-rcna94766 しかし通常、こうした詐欺を働くのは
「セックスロボットは悪なのか」 という議論がある。 精巧につくられた等身大のドールで、触れると温かい。センサーとAIにより、ユーザーが望む反応を学習して応答する、ロボット工学と人工知能の粋を集めたアンドロイドだ。 愛情を深め合うコミュニケーション手段としてのセックスが蔑ろにされ、女性蔑視や暴力へつながるかもしれない。一方で、感染症の心配もなく安心して愛情を注げるパートナーに救われる人もいるだろう。 あるいは、 「アンドロイドが運転する車が事故を起こしたら、誰に責任を問うべきか?」 という議論がある。 AIは人間よりも安全運転できるだろうから、自動運転をベースとした車社会を設計すべきだという意見がある。一方で、プログラムや学習データの不具合によってAIが暴走する可能性は残されており、その影響は計り知れないという人もいる。 こうした議論は、論点が噛み合わないか、漠然とした話になりがちだ。意識と
エンジニアの間では発売から瞬く間に広まった本書ですが、まだ読んでない方々向けに本記事を書いてみました。要約なので、ここは重要だなと感じたポイントに絞って本記事に記載します✏️ 概要 まず結論からいうと、仕事の進めかたや捉え方という点でとても学びのある良書です。すでに多くのエンジニアには知れ渡っていますが、もっともっと知れ渡って欲しい本です。 内容としては、著者の牛尾さんがアメリカのMicrosoft社(Azure開発)で得た経験がそのままに書かれています。最初はアメリカのエンジニアに劣等感を感じていたようですが、その理由を言語化して、実際にどうすれば彼らと肩を並べるエンジニアになれるかが書かれています。 また全体的にアメリカのエンジニア思想を爆推ししているので、こっち系の思想が好きな人は一瞬でハマると思います。私もどちらかと言えば圧倒的にこっちのタイプですが、読むときには偏らないように中立
筆者はこれまで、定期的にVimのプラグイン紹介の記事を定期的に投稿していたのですが、2019年のVim AdventCalenaderに投稿したNeovimでモダンなPython環境を構築するv2(LSPを添えて)以降、ほとんどプラグイン紹介記事を執筆していませんでした。 他のかたの記載されるNeovim環境構築記事を見るたびに、筆者も自分の環境を紹介したいと常々思っていました。 ワシの使っているNeovimプラグインは200個近くあるぞ vim沼: NeovimのReact、TypeScript、Tailwind CSS用セットアップ Neovimでのフロントエンド開発環境 2022 しかしNeovim v0.5のリリース以降、増え続けるluaプラグインの洪水に飲まれ、筆者のNeovim環境はプラグインを入れては消しを繰り返し、安定しない日々を過ごしていました。 Neovim v0.5リ
本連載では、「世の中で活躍するエンジニアの過去の失敗」にフォーカス。どのような失敗をし、どう対処し、そこから何を学んだのか。仕事で失敗してしまった時の対処法や心構えを先輩エンジニアから学ぼう! どれほど優れた人であっても、失敗はある。「失敗は成功の母」というように、失敗が個人の成長を促す側面があることを知りつつも「周囲に迷惑を掛けたくない」「叱られたくない」一心で失敗を恐れる人は少なくない。 当連載では、現在、業界で活躍している先輩エンジニアの「失敗」にフォーカスし、いかにして失敗を成長の糧にできたのか、ご本人に振り返ってもらいながら、成長の糸口を掴むコツを探っていく。 記念すべき第1回目では、メルカリCTOの名村卓さんにお話を伺った。複数社の技術顧問としても活躍し、サイバーエージェントの藤田晋社長にも「国宝級エンジニア」と言わしめる人物。一見、「失敗」というイメージが結び付きにくい名村さ
まつもとゆきひろ氏がソフトウェア開発に役立つ2冊の書籍を紹介 『失敗の科学』と『APIデザインケーススタディ』から学べること #11 「失敗の科学」 オープニングトーク まつもとゆきひろ氏:まつもとゆきひろです。月曜日に放送して以来、ちょっと間が空いてしまいました。今日これを録音しているのは、(2022年)6月25日の土曜日なので、月曜日から土曜日まで録音できなかったということになります(笑)。 「Voicy」は、一発録りで流す仕組みで、編集をほとんどかけていないので、そういう意味で言うと、習慣化して毎日10分とか録れば、すぐに毎日できるようになると思うんですけれども、まだ習慣になっていないので、忙しいとこうやってつい後回しになって、じゃあ、次の日、とかなってしまいがちなのが現状です。 例えば、毎日「Wordle」をするとかですね(笑)、日記を書くとかですね、それから、「mruby」に1日
Source:imgflip.comAs I write this on the 25th of April, I am still reeling from the announcement of IBM’s acquisition of Hashicorp. When I first heard the rumours yesterday, I was concerned about the future of possibly my favourite Infrastructure-as-code (IaC) tool. It has long been obvious that Hashicorp has been struggling to make money, making a $274 million loss in 2023. This undoubtedly led t
記事執筆:山本ぽてと ◇はじめに この連載は在野に関わる人々を応援するものだ。 前回の更新から1年以上時間が経ってしまった。コロナ禍によって、在宅時間を持て余す人が増え、「独学」に光の当たった1年であったように思う。読書猿さんの『独学大全』(ダイヤモンド社)が大ヒットし、英語学習についての新書が注目され、『BRUTUS』では「勉強」特集が組まれた。大学によるYouTube授業なども盛んだ。 ちなみに『BRUTUS』の「大人の勉強案内」では、荒木優太さん(第1回)、山本貴光+吉川浩満(第2回)も登場している。私も3つの記事に関わった。この「在野に学問あり」も更新をする千載一遇のチャンスであったが、ぼんやりしているあいだに時間が経ってしまった。 さて、今回はまさに『独学大全』が売れに売れている読書猿さんに話を聞いた。インタビューはコロナ禍であることと、読書猿さんが遠方にお住まいのため、「在野に
IBMによるHashiCorpの買収が正式に発表されました。買収価格は64億ドル(1ドル150円換算で9600億円)(HashiCorpの発表、IBMの発表)。 買収交渉が行われているとの報道が昨日から行われており、それが具体化したことになります。 HashiCorp is excited to join @IBM to continue building the platform of choice for multi-cloud automation. @armon shares his thoughts on how this serves our community, customers, partners, and product innovation: https://t.co/xBIN6FkVsE (link contains important information) p
骨伝導ヘッドセットAfterShokzを使い始めて1年以上。 もう完全に手放せない。 メガネと同じくらい装着しっぱなしの生活になっている。 骨伝導ヘッドセットを使い始めて1年 1年ほど前に骨伝導ヘッドセットの記事を書いた。 この時は使い始めて1ヶ月の時点だった。今回はさらに1年使った感想である。まずは前回の復習から始めよう。 俺が使っているのはワイヤレスの骨伝導ヘッドセット『AfterShokz Air』である。 AfterShokz Airオープンイヤーワイヤレス骨伝導ヘッドフォン、ポータブル収納ケース付き、ミッドナイトブルー AftershokzAmazon 骨伝導なので、常に耳は開放状態となる。外部の音も普通に聞こえるし、着けっぱなしでも外耳炎になるリスク*1も無い。 Msahid manik / CC BY-SA, Link この特徴のおかげで1年前 (使用1ヶ月) の時点で、平日
唱えたことが現実になる。 これはオカルトではなくテクノロジーの話だ。 常時装着したヘッドセットが人生を変える。 常時装着の有効活用 左耳の前を触ってみよう。きっとそこには「ボタン」がある。 そこにはブームマイクしかないが、という人は右側を触ろう。 本記事はこのボタンを有効活用する記事である。 何も無いとのたまう旧人類は早くヘッドセット常時装着(アップデート)してほしい。 前回の記事への反応で、「読んでAfterShockzを買った」というコメントをわりと見た。記事を書いた者として、せっかく買って常時装着するのなら有効活用してほしい。そこで前回の記事では触れていなかった活用方法、リマインダーへの音声入力の話をする。これは音声アシスタントへの入力端末を常時装着することの、真の価値を感じられる手法である。 これを前回紹介しなかったのは、俺はApple Watchで音声入力をすることが多いからであ
色々あって WebAssembly の component model を調べていたら、未来が見えた気がしたのでここに書いておきます。 「今の WebAssembly」 とは何か WebAssembly の Web の部分は忘れてください。これは単に JVM version 20xx です。ポータブルなバイナリ仕様です。 実行にあたっては今はホスト言語として JS が使われていますが、実際にはホストがJSである必要すらなく、なんならホストが不要なスタンドアロン環境すらあります。(wasmtime/wasmer) じゃあ WebAssembly は何かというと、サンドボックスで実行される VM の仕様です。比較的高水準なバイナリで、 V8 や Spider Monkey に付属する WebAssembly Runtime や、 Wasmtime や Wasmer といった WebAssemb
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く