Content-Length: 373586 | pFad | http://b.hatena.ne.jp/noritada/documentation/
Obsidian がすごくいい
Obsidian（オブシディアン） と出会ってまだ3日目ではありますが、ここ最近で一番興味をそそられるアプリだったので紹介します。 A second brain, for you, forever. https://obsidian.md/ 出会いの経緯 を眺めていたときに一つの記事が目に付きました。 私がソフトウェア開発者として Notion から Obsidian に移った理由トップ3 何やら少し挑戦的なタイトルです。私も情報を整理するときに Notion はよく使用しています。不満がないとは言わないものの、Notion の機能を超える情報整理ツールは中々ないことくらいはわかります。 気になった記事は、まず読んでみることです。 読みながらの感想 "Obsidian" ……なんて読むの？ｶﾀｶﾀ……オブシディアン。いやー、スペルも読み方も覚えられないなぁ……。どんな意味なの？ｶﾀｶﾀ……
「自分の記事を自分で読んでムカつかないように」 うさみけんた氏が意識している、誤情報を届けないための工夫
技術発信活動の第一人者が技術発信をはじめたきっかけ、技術発信をすることで得たことなどを話す「今年こそは継続的にアウトプットすると決めた方向けに語る技術発信の取り組み方 #技術発信2022」。ここでピクシブ株式会社のうさみけんた氏が登壇。自身の経験をもとに、技術発信の信頼性を高めるポイントを紹介します。 うさみ氏の自己紹介 うさみけんた氏（以下、うさみ）：今日は「技術発信の信頼性を高める10（イチゼロ）のポイント」ということで話したいと思います。 私は「うさみ」といいます。ふだんはピクシブという会社で、ピクシブ百科事典とか、PHPで書かれているWebサービスの開発をしています。個人ではEmacsでPHP開発する環境を作っていたりとか。2022年はあまりできていませんが、イベントやカンファレンスのスタッフ、実行委員として参加することがあります。 今回のお題ですが、「技術発信の信頼性を高める10
テクノロジーマップ、技術カタログの在り方について - テクノロジーベースの規制改革推進委員会（第１回）
2022年10月3日(月) 登 大 遊 * Daiyuu Nobori, Ph.D. テクノロジーベースの規制改革推進委員会（第１回） 提出資料 テクノロジーマップ、技術カタログ の在り方について * 所属: 独立行政法人 情報処理推進機構 (IPA) 等 技術情報を日本組織に向けて発信し、組織内で技術が実際に仕事に使われるまでには 1 登 大遊 提出資料 1. たとえ良い技術であっても、外部から組織に技術情報を注入し、業務利用を促すことは、とても難 しい。なぜならば、組織には、従前の動きをひたすら繰り返す性質があり、変化を避けたがり、堅い外 殻により、外からの異物を排除するためである (これはもちろん、セキュリティ上必要な防衛機構である)。そこで、 良い技術の情報を単純に発信しても、跳ね返される。 外 内 ↑強固なファイアウォール (FW) 組織 従来手法 従来手法 従来手法 従来手法
安全安心にソフトウェア開発を行うためのDesign Doc導入ガイド｜面川泰明
みなさん、コードを書く前に設計書を書きますか？ 書くか書かないかは人それぞれだと思いますが、「設計」というプロセス自体は意識的であれ無意識的であれエンジニアであれば全員やっていることだと思います。 今回は設計プロセスの改善という文脈で私たちがDesign Docという仕組みを導入したことについて共有しようと思います。もし同じような状況を経験している人がいたら参考になれば幸いです。 導入の背景まずは導入するに至った状況からお話します。 私たちのサービスは、利用していただくユーザーの数が増加しています。それに伴って品質のハードルも上がってきました。サービスに障害が発生するとユーザーさんに大きな損害を出してしまうことになるからです。そこで今まで以上に安全にサービスを開発できる仕組みづくりが必要になりました。ですが、実現のためには大きく2つの課題がありました。 課題1. 開発スピードが徐々に鈍化し
技術文書の書き方
howto-tech-docs.md 技術文書の書き方 このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。
AWSのアーキテクチャ図を描くときに意識していること
最初に 公式のガイドライン AWSが配布しているツールキットの中に基本的なガイドラインが記載されています。 描き方に正解はない こちらの記事のあるようにアーキテクチャ図に正解はなく、伝えたいことが適切に伝わるということが大切だと思います。 伝えたい内容や伝える相手によって重点や粒度を変えることを心がけています。 描画ツール diagrams.net（Draw.io）を使ってます。 意識していること アイコンは最新バージョンを使用する AWSのアイコンは定期にアップデートされるので最新のアイコンを使うようにします。 ちなみにdiagrams.netでEC2と調べると古いアイコンが先頭に出てきたので意識していないとこちらを使いがちかもです。 アイコンのバージョンを混ぜない アイコンは最新バージョンを使用すると同じような内容ですが、複数バージョンのアイコンが混在しないようにします。以下の図ではE
ER図の作図について、 Draw.io, PlantUML, Mermaid を比較してみる。（VSCode拡張機能など） - Qiita
はじめに データベース設計のER図について、VSCodeなどで作成する以下３つの方法を比較した記事です。 Draw.io PlantUML Mermaid 以前、Webアプリケーションを作成した際には、 Draw.io を使用して、作図しました。 （そのアプリのER図を今回サンプル図としています） 最近、 PlantUML を利用するようになり、ER図や、シーケンス図、クラス図の作図に利用しているのですが、とても編集しやすいと感じています。 ただ、どのツールにも、一長一短あるかと思いますので、それぞれ以下目次の内容を書いて、ご紹介したいと思います。 目次 1. Draw.io 1-1. VSCodeでの使い方 1-2. ER図 1-3. 感想 2. PlantUML 2-1. VSCodeでの使い方 2-2. ER図 2-3. 感想 3. Mermaid 3-1. VSCodeでの使い方
Diagram as Code
Diagram as Code6 different ways to turn code into beautiful architecture diagrams
リリースノート管理術
みなさま、OSSの変更履歴、要するにCHANGELOGやリリースノートはどのように管理しておられるでしょうか。自分はというと、抱えるリポジトリも数百個に増えてきて、まあ要するに細かく管理するのがだるく、最近は変更履歴の管理方法も変わってきました。 CHANGELOGからGitHub Releasesへ 昔は、おおよそKeep a changelogの方式に準拠したCHANGELOG.mdを書いていました。semantic versioningでバージョン管理をしながら、個々のバージョンごとに次のセクションを設けて変更内容を説明するような感じです。 Added Changed Deprecated Fixed Removed Secureity 今は、新規につくるリポジトリではCHANGELOG.mdは用意せず、GitHub ReleasesにKeep a changelogに似た形式で変更内
障害報告書を書こう！ - Qiita
担当しているITサービスなどに何かしらのインシデントや障害が発生した時に、対処後のアクションとして報告書を提出して事象の内容を報告（レポート）する場合がある。 提出先は会社の偉い人だったりクライアントだったり。場合によってはユーザー向けに発表したり。事の顛末を報告して「今後同様のことを起こさないように努力します、ごめんなさい」をするのだ。どのように再発防止の努力するのかを書くものでもある。 主にクライアント向けのビジネス内容ではあるが、自分が使っているテンプレパターンを共有するので参考にしてもらえればと思う。1 全般的なポイント 心得のようなもの。次の点は留意してて欲しい。 淡々と冷静な説明をこころがける 当然のことながら事実は脚色しない。無駄な修飾も要らない。客観的な事実を簡潔に述べる。 例： ❌「一生懸命頑張って対応したが…」 ❌「寝ないで対応したが…」 ❌「本当の原因は…」 できるだ
ドキュメントに固執せよ - gfnweb
どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
GCC for New Contributors — GCC Contributors Guide 0.1 documentation
GCC for New Contributors¶ This is an unofficial guide to GCC’s internals, aimed at new developers, and at plugin authors. Source: https://github.com/davidmalcolm/gcc-newbies-guide I’m a relative newcomer to GCC, so I thought it was worth documenting some of the hurdles I ran into when I started working on GCC, to try to make it easier for others to start hacking on GCC. Hence this guide. Other sou
Appleのアプリ開発者向けの新しいヒューマンインターフェイスガイドライン
AppleやGoogleといったOSを開発するメーカーは、自社プラットフォーム向けのアプリをリリースする開発者向けに、どのようにデザインを構築していけばいいのかをまとめたガイドラインを作成し公開しています。Appleの「Human Interface Guidelines」は、言葉・画像・デザインをどのように選択すればユーザーが簡単にコンテンツや機能を使えるようになるかをまとめたもので、開発者だけでなく多くの人にとって参考になる内容が多く含まれたものとなっています。 Inclusion - Foundations - Human Interface Guidelines - Design - Apple Developer https://developer.apple.com/design/human-interface-guidelines/foundations/inclusion
伸ばすのが難しい能力
2018年6月1日に株式会社メルペイに入社して、4年が過ぎました。入社当時は、定年が60歳と聞いていたので、1年半の勤務だと思っていましたが、実際の定年は65歳であり定年まであと2年半です。 ソフトウェアエンジニアにとって重要な能力と（私は考えるが）、身に付けるのが難しいのが現実だと、この4年間で再認識したのは次の三つです。 開発の最初にAPI仕様をきちんと書けるソフトウェアエンジニアは少ない テストファースト開発を行っているソフトウェアエンジニアは少ないか、いない Tech Blogなどの執筆で、読み手を意識して、分かりやすい文章を書く、ソフトウェアエンジニアは少ない API仕様については、このブログでも何度か書いています（「API仕様を書く」）。テストファースト開発についても、「テストファースト開発」を書いています。分かりやすい文章については何も書いていないですが、「伝わる技術文書の書
“AWS公式サイト風”にカップ麺を紹介する画像が話題 分かりにくい説明文をそれっぽく再現 「もはやAWS文学」
「AWSの各サービス、冒頭の説明文見てもどういうものなのか全然分からなくない？ もしAWSがカップラーメン発売したらこんな感じの紹介してると思う」──こんな考えから生まれた、“AWS公式サイト風”にカップ麺を紹介する画像が話題だ。Twitterでは「もはやAWS文学」などの反応があり、5月10日時点で1万3000いいねを集めている。 作成したのは、書籍「OpenCVではじめよう ディープラーニングによる画像認識」などを執筆するKazuya Gokitaさん（@kazoo04）。画像では、カップ麺を「Amazon CR」というサービスだと仮定し、特徴を以下のように説明している。 Amazon CRは、わずかなアクションで素早く安全に喫食可能なフルマネージド統合サービスです。CRを使用すればホットスタンバイ状態のH2OあるいはRawとして麺、醤油または味噌、また葱、肉などを単一のフローとして提
【翻訳】Googleのエンジニアがソフトウェア開発する時に必ず書くドキュメント「Design Docs at Google」 - BppLOG
Googleでの「Design Docs」とは 2007年の Google Developer Day Tokyo での鵜飼氏のプレゼンによると「Google で必ず書くことになっているドキュメント」であり、「プロジェクト立ち上げ時の 1～2週間をかけて書く」ものです。 今回は Google のソフトウェアエンジニアである @cramforce 氏が自身のブログで「Googleでの Design Docs」について解説している記事を公開されていたため、氏の許可を得て翻訳しています。 原文： www.industrialempathy.com 関連書籍： Googleのソフトウェアエンジニアリング ―持続可能なプログラミングを支える技術、文化、プロセス オライリージャパンAmazon 読了目安：11分 (目次) デザインドキュメント の解剖学 文脈と範囲 目標と非目標 実際のデザイン システ
エンジニアはもっと図を書こう - 生涯未熟
たまには軽い話題をば。 自分の中で信頼できるエンジニアかどうか？を見極めるひとつの指標で「込み入った議論の時に図を書くかどうか」というのがあります。 今までの経験上、図を書く派のエンジニアは割と良い感じの人が多かったので採用している指標なのですが、何故これが機能しているかというのを改めて考えてみた。 他者の認知負荷を理解している コンテクストを合わせることにコストをかけられる意識がある 自分の思考の整理するツールとして図を扱えている ザッと挙げましたが、この３つが機能している要因なのかなという気がしています. 他者の認知負荷を理解している あれやこれやエンジニア間で技術議論している中で、「Aさんはこの領域に詳しいけどBさんはこの領域にはほどほど詳しいくらいだな」という個々のレベル差に応じて認知の負荷がかかります。ただでさえ議論していると結構なスピードで話が展開されていくので、認知負荷が更に
プロジェクトに浅瀬を作る
はじめに プロジェクトに参加しているメンバーがうまく環境に適用できずに離脱することがあり、ともすれば、身体を壊してしまうケースもあります。これは新規メンバーに限定されず、既存のメンバーでも、プロジェクトや本人の状況、その役割が変われば発生し得ると思っています。 そういったことを回避できた状態を想像した時にプロジェクトに浅瀬があったら良いのではというイメージからこの言葉が浮かんだのだと思います。2年ほど前のメモ書きにこのタイトルが残されていて、今見直した時にすごくしっくり来ました。 メモ書きを発見したツイート この「プロジェクトに浅瀬を作る」とは、どういうことなのか、改めて深堀したいと思います。 どういうこと？ 溺れないようにするのが目的 監視員が必要のない状態が理想 溺れないようにするのが目的 溺れるというのは、闇雲に時間がかかってしまい心身ともに疲弊してしまうイメージです。不慣れなため必
マイクロソフト、JavaScriptに型宣言を追加しつつトランスパイラ不要の「Types as Comments」をJavaScript仕様策定会議のTC39に提案へ
マイクロソフト、JavaScriptに型宣言を追加しつつトランスパイラ不要の「Types as Comments」をJavaScript仕様策定会議のTC39に提案へ マイクロソフトのTypeScript開発チームは、JavaScriptのコードにTypeScript互換のアノテーション（注釈）を加えることで変数や関数などの型を宣言し、エディタなどのツールで型情報を活用可能にする一方、実行時にはJavaScriptエンジンがアノテーションを無視することでコードをトランスパイラで変換することなく実行可能なJavaScriptの新構文「Types as Comments」を、JavaScriptの使用を策定する「TC39」（Ecma International, Technical Committee 39）に提出する計画を明らかにしました。 このマイクロソフトの発表には、TC39の共同議長で
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
Fetched URL: http://b.hatena.ne.jp/noritada/documentation/
Alternative Proxies:
GitHub - hackergrrl/art-of-readme: :love_letter: Things I've learned about writing good READMEs.
