こんにちは。壮（@sew_sou19）と申します。 メガベンチャー企業でエンジニアとして働いています。 エンジニアにジョブチェンジした当初は、ドキュメントの書き方なんてこれっぽっちも分かりませんでした。読みやすいドキュメントを書くことが本当に苦痛だったのですが、考えて、試行錯誤し続けた結果、以下のような評価を得るに至りました。 リーダーから「君は情報の整理が上手でドキュメントが本当に読みやすい。チーム全体の能力向上に繋げたいからドキュメント書く際のポイント共有してほしい」と言われたので、意識していることを言語化しつつテクニカルライティングの本でインプットしてるけど、学びが多い。ついでにnoteにもまとめてる — 壮 (@sew_sou19) November 28, 2022 そこでこのnoteでは、僕がドキュメントを作成するときに、特に意識して実践している7つのことを書きます。（本当は2
システム構成図をテキストで
Gigazineさんでdrawthe.netを取り上げていたので紹介です。使い方はGigazineさんのほうが丁寧なので、気になる方はチェックしてみてください。（2020年12月1日、追記） drawthe.netとは cidrblock/drawthe.netは複雑なネットワーク図も「テキストで書いてブラウザ上でSVGレンダリングできるようにしよう」というコンセプトのもと開発されたツールです。下図のように複雑な構成図も精度高く描くことができます。 拡大してみると情報量が多いこと、またいかに整っているかがわかると思います。 デモサイトも用意されているので、サクッと試したい場合はコチラが便利です。コードはGitHubで公開されています。更新が2017年末で止まってしまっているのが玉に瑕ですが、十分な性能を発揮してくれます。 drawthe.netを使いたい理由 美しい構成図といえばInter
手順書フォーマットは千差万別 みなさんは自己流または、組織やプロジェクトで定められた手順書のフォーマットはありますか? 私は自己流の手順書フォーマットがあります。 自己流の手順書フォーマットがあるといっても、かなり扱いがふわふわしているので、備忘やメモの意味合い強めでまとめていきます。 「もっとこうした方がいいよ!!」などフィードバックがあれば、ぜひお願いします! いきなりまとめ 手順書はExcelやスプレッドシートではなく、Markdownで書く 手順書はgitで管理する 5W1Hを意識して手順書を書く 基本的にはCLIを使った手順書にする 手順書はExcelやスプレッドシートではなく、Markdownで書く 手順書をExcelやスプレッドシートで書くメリット・デメリット 手順書をExcelやスプレッドシートで書いている方も多いと思いますが、私はMarkdownで書いています。 Exce
短いメッセージを書くことはできても、まとまった文章を書くのに苦労している人は多いのではないでしょうか。 この記事では、まとまった文章を作るときの技術を学ぶことができる記事や学習コンテンツを紹介します。新人エンジニア向けです。 文章の「型」を学ぶ まとまった文章を書くには、「型」が必要です。頻繁に使うものは、「型」を覚えてしまいしましょう。 バグレポートの書き方を学ぶ エンジニアとして書く文章の代表例が、バグレポートです。 バグレポートでありがちな失敗として「何が問題だと思っているのか」が伝わらないというものがあります。 これを防ぐために、「期待する結果」「実際の結果」「再現手順」の3つを必ず書くようにしましょう。 質問の書き方を学ぶ エンジニアが扱う技術は、最初はわからないことだらけです。 それを解決するために、質問の文章を作成する技術が必要となります。 概ね下記の4つの情報があれば、良い
メモアプリの知見のお返しにきた
去年の大晦日に「メモアプリの知見を貸してほしい」という増田を書いた者です。750超のブックマークと注目をいただきまして大変感謝しています。 https://anond.hatelabo.jp/20221230142549 あれから半年経過してみて自分の使うメモアプリが定まってきただけでなく、メモの意識およびスタイルに変革が生じました。これを、皆さんからお借りできた知見の「お返し」としてご報告したいと思います。 「中身に興味無いけどブコメしたいからブクマした」という人は、簡単に作れそうな激辛料理を教えてください。最近自炊が楽しいもので…中華ばっかりですが。 コメントが「メモの意識変革」をくれましたブコメは270件、増田のトラバは50件と膨大なアドバイスや激辛スナック情報を頂いて、まずは発見がありました。 ある人が「タラタラしてんじゃね〜よ は激辛？」と聞いてきた折に「自分は激辛とは思ってない
と注記しています。 すっきり分けにくい場合も 動詞の下に付けて補助的に使えば漢字の意味が意識されないと考えられるわけですが、形だけでわかるとは限りません。 動詞の下に付いていても 「傘を学校に置いて来てしまった」「子供を家に置いて行く」 などは、「来る」「行く」にも意味があって漢字で書いてもよさそうです。 同じ「しれない」でも 「彼ならあんなことも言うかもしれない」 「あんなことを言う彼の気が知れない」 ――と、後者は漢字で書いてもよさそうです。 「意味が薄れた」かどうかは微妙で難しいものがあります。毎日新聞用語集は「言う」「いう」の書き分けをこのように例示しています。 「大家といえば親も同然」という例が挙がっていますが、「といえば」でも 「気にならないと言えばうそになるが……」 のように使う慣用句では、実際には言わないけれど「口に出して言ってしまうと」という感じなので「言」を使ってよさそ
こんにちは丸山@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日 これらのドキュメントは個人的にわりと良く書けたと思ってますし、
プログラマーがドキュメントを書かない理由
この記事は、著者の許可を得て配信しています。 Why programmers don’t write documentation 最近ではずっとコードのドキュメンテーションに関連した記事を書いていたので、当然、私のMediumのおすすめ記事には「開発者がドキュメントを書かない本当の理由」という記事が表示されるようになりました。この記事では、ドキュメントを書くための優れたツールがないことが、ソフトウェアエンジニアが自分の作業や判断をドキュメンテーションする意欲を失わせる最大の原因について書いています。 私は普段、特定の記事を批判したりはしませんが、この記事には怒りを覚えました。このライターは図解ツールについていくつかメリットに関して述べてはいますが、全体的に誤解を招くような内容になっており、この重要な問題をより分かりにくくさせています。2つの図解ツールを比較して、どちらも不十分なツールである
コーディングのようにノートを取る技術 - Qiita
Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? はじめに 何かを学習するとき、ノートを取っているでしょうか？ 小学生の頃や中学生・高校生の時の「ノート」は紙に手書きだったかと思います。 しかし、最近になってからはパソコンを使ってノートを取る、という選択肢が増えました。 その変遷の中で生まれたパーソナル・ナレッジ・マネジメント(Personal Knowledge Management) という考え方があります。 その考え方を共有できたらと思います。 直感的なデジタルノート術の原罪 ケース1: ひたすらに手を動かす 学生の頃、黒板に書かれた内容をそのまま必死にノートに写している人がいた
プロジェクトに浅瀬を作る
はじめに プロジェクトに参加しているメンバーがうまく環境に適用できずに離脱することがあり、ともすれば、身体を壊してしまうケースもあります。これは新規メンバーに限定されず、既存のメンバーでも、プロジェクトや本人の状況、その役割が変われば発生し得ると思っています。 そういったことを回避できた状態を想像した時にプロジェクトに浅瀬があったら良いのではというイメージからこの言葉が浮かんだのだと思います。2年ほど前のメモ書きにこのタイトルが残されていて、今見直した時にすごくしっくり来ました。 メモ書きを発見したツイート この「プロジェクトに浅瀬を作る」とは、どういうことなのか、改めて深堀したいと思います。 どういうこと？ 溺れないようにするのが目的 監視員が必要のない状態が理想 溺れないようにするのが目的 溺れるというのは、闇雲に時間がかかってしまい心身ともに疲弊してしまうイメージです。不慣れなため必
情報の見つけやすさを追求する - 社内ドキュメンテーションの階層整理術 - KAKEHASHI Tech Blog
カケハシのプラットフォームチームでソフトウェアエンジニアをしているすてにゃん (id:stefafafan) です。今回はチームに配属されて数ヶ月の私が、いかにして社内ドキュメンテーションの階層構造を整理し、情報の検索性を向上させたかについてお話します。 はじめに この記事の想定読者 課題意識 メンバーへの共有と相談 社外事例の調査 esa の階層整理 第 1・第 2 階層の整理 ストック情報とフロー情報を意識した階層の整理 esa の機能をフル活用する 効果や今後について はじめに カケハシでは全社的にドキュメンテーションツールとして esa - 自律的なチームのための情報共有サービス を利用しています。それぞれのチームやプロダクトごとに階層を切ってドキュメントを書いています。 プラットフォームチームでは認証基盤などの社内プラットフォームシステムを開発しているため、自チームが運用する各種
Amazonのミーティングはとても奇妙な形で行われることが多い - ミーティングの最初にドキュメントを参加者が黙読するのだ。議論は全員が読み終わったことを確認してからスタートする。基本的に文章を読まずにいきなり発言し出したりということは許されない。大人数が一つの部屋に集まり、一つの文章を黙って読む姿は結構シュールである。 私はこの奇妙なミーティングをする会社に7年ほど勤めていた。こういった環境で生き残るには人に読ませる、よいドキュメントを書かねばならない。しかもアメリカで働いているのだから当然英語で書く必要がある。しかしながら私は帰国子女でもなく、特段英語が得意というわけでもない。最初の頃に書いたドキュメントは複数人にレビューされていつも真っ赤っかになっていて、そのマークアップの量を見ては鬱々としたものである。が、小さな子供とVisa問題を抱えて異国の地でクビになるわけにもいかない。英語弱
「リーダブルなテストコードについて考えよう ～VeriServe Test Automation Talk No.3～」で使用したスライドです。 https://veriserve-event.connpass.com/event/243280/ 登壇動画はこちらで公開されています。 http…
「うまい文章を書ける人」は “この5つ” が自然とできている - STUDY HACKER（スタディーハッカー）｜社会人の勉強法＆英語学習
「文章力」は、社会生活を送るうえで基本的かつ重要なスキルです。きれいで伝わる文章を書ける人はやはり信頼したくなりますし、逆に文章がめちゃくちゃだと「この人は大丈夫かな……？」と敬遠したくなるもの。メールやチャットがコミュニケーションの主流となった現代では、文章力がその人の印象を左右すると言っても過言ではないでしょう。 そこで今回は、「文章を書くのが苦手……」「文章だとなぜか理解してもらえない……」と悩んでいる人のために、文章力向上のコツを5つご紹介します。 【1】ゴールから逆算して必要なことを書く かつて進研ゼミ小論文編集長を務めた文章表現インストラクターの山田ズーニー氏は、「文章の良し悪しは目指すゴールによって違う」と述べます。たとえば、依頼メールであれば「人を動かすこと」、履歴書やエントリーシートであれば「内定」、小説であれば「感動」がゴールになるでしょう。このゴールがあやふやだと、た
大事だけど AWS 構成図では省略してしまうことが多いサービスについて - サーバーワークスエンジニアブログ
コーヒーが好きな木谷映見です。 今回は小ネタです。AWS 構成図を書く際、省略してしまうことが多いサービスについて思いを馳せました。 よくある？構成図 リージョン アベイラビリティゾーン ルートテーブル AWS IAM インスタンスプロファイル Amazon EBS Elastic IP Elastic network interface（ENI） セキュリティグループ セッションマネージャーする時のエンドポイント 最終構成図 終わりに よくある？構成図 よくあると思われる構成図を描いてみました。 AWS になじみがある方から見ると、 「ふむ、パブリックサブネットとプライベートサブネットに 1 台ずつ EC2 インスタンスがあって、プライベートサブネットのインスタンスにはセッションマネージャーでログインするのかな？S3 バケットもあるな」 くらいの想像ができるかもしれません。 リージョン
こんにちは。「リーダブルコード」を先月読破して、感銘を受けた弁護士の人です。 なにに感銘を受けたかというと、「エンジニアが高級言語を効率的にコーディングするための工夫」は、契約という言語をコーディングするために援用できることがとても多いということです。 例えば、リーダブルコードは「関数には空虚な名前（tmpとかretvalとか）でなく、エンティティの実体に即した名前をつけよう！」と提案しています。 これめっちゃわかります！！！なぜなら、契約言語では当事者というクラスの表現のために「甲」「乙」という定義を未だに使います。そして、甲と乙を逆に書いてしまったままReviewを通過することが実際によくあります。オライリーさんには激怒されるでしょう。 しかし、よく考えると高級言語と契約言語が似ているのは当然だと思うようになりました。それは、どちらも「一定のインプットを入れると、必ず一定のアウトプット
みなさん、コードを書く前に設計書を書きますか？ 書くか書かないかは人それぞれだと思いますが、「設計」というプロセス自体は意識的であれ無意識的であれエンジニアであれば全員やっていることだと思います。 今回は設計プロセスの改善という文脈で私たちがDesign Docという仕組みを導入したことについて共有しようと思います。もし同じような状況を経験している人がいたら参考になれば幸いです。 導入の背景まずは導入するに至った状況からお話します。 私たちのサービスは、利用していただくユーザーの数が増加しています。それに伴って品質のハードルも上がってきました。サービスに障害が発生するとユーザーさんに大きな損害を出してしまうことになるからです。そこで今まで以上に安全にサービスを開発できる仕組みづくりが必要になりました。ですが、実現のためには大きく2つの課題がありました。 課題1. 開発スピードが徐々に鈍化し
SWET第二グループのKuniwakです。本記事では画面仕様（後述）の仕様書に対する静的検査器を開発した事例について紹介します。 伝えたいこと 画面表示と画面遷移を記述する仕様書は機械可読にできる 仕様書が機械可読であれば仕様の静的検査ができる 静的検査によって自身の担当範囲の15%の画面から計40件弱の欠陥を発見した 機械可読な仕様書にはさらなる応用が見込める おさらい：仕様とは 仕様の定義はいくつかあります。 ここでは仕様とは実装の正しい振る舞いを定める基準とします。 ある実装が正しいと判定されることを、実装が仕様を満たしたといいます。 誰による判定でも実装が仕様を満たしたかどうかの判定結果は一致すべきです。 さて実装の欠陥と同様に、仕様にも欠陥が生じえます。 本来正しいと意図した実装の振る舞いを誤っていると判断したり、その逆に誤っていると意図した実装を正しいと判断する仕様には欠陥があ
新規事業は社内ドキュメント戦略が大事な話｜細見 優太
みなさんこんにちは、こんばんは、カミナシの細見(@yuta_hosomi)です。 カミナシはマルチプロダクト戦略構想のもと、複数のProduct開発と提供を進めている真っ只中です！ そのなかで、ビジネス側のチームも新規事業で新しく組閣され、どんどんニューカマーがジョインしてくるなかで、「ドキュメント戦略を作って運用した」お話しです。 チームに参画して、最初に読まないといけないとされるドキュメントがこれ。これが今日のテーマですこういった、社内ドキュメントの戦略について私も色々読み漁ったのですがめぼしいものや、実例があまりなく、整理整頓好きのかたのヒントやお手伝いになれば幸いです。 ですが、このnoteはただどうドキュメントをつくればいいという話ではなく何のためにするのか、それに基づきどうドキュメントを作るのか？それをどう仕組み化し、マネジメントするのかについてが重要だと思っているので、やや前
＜書くことが苦手な人でも「オレオ公式」を知ることで、誰でも論理的な文章がすぐに書けるようになる＞ ハーバード大学で受け継がれているライティングメソッドから生まれた「オレオ公式」。 書くことが苦手な人でも「オレオ公式」を知れば、論理的かつ説得力のある「伝わる文章」の達人になれる。 『作文宿題が30分で書ける! 秘密のハーバード作文』（CCCメディアハウス）の「第1章 ハーバード大生みたいに考える」より一部抜粋。 作文上手になるためのセンターピンをねらえ！ 以前『ニューヨーク・タイムズ』の記者が書いた『習慣の力』（チャールズ・デュヒッグ著、講談社）という本が、世界中で話題になりました。人間の習慣の秘密について著者の考えをまとめた本です。 この本の中で著者は、「ボウリングのセンターピンを1本倒すだけでほかのピンも次々と倒れていくように、まず、その人が変えたいと思うもっとも大きな習慣をひとつ変える
新しいプロジェクトに参加してローカル環境を作り始めると、何かとエラーに遭遇します。 また、設計や実装について開発者に相談したり、コードレビューを依頼することもありますね。 開発者が近くにいれば、（それなりに、程よいタイミングを見計らって）話しかけて、エラーの原因を調べてもらったり、設計方法をホワイトボードにスケッチしながら相談できますが、リモート開発ではそうはいきません。 リモート開発で成果を上げるためには、このブログのように何の装飾もインタラクティブ性もない文章で、自分の状況や相談したい事柄を正確に伝える必要があります。 とはいえ私は昔、「文章がわかりにくい」と毎日、毎日上司にフィードバックをもらうくらいには文章を書くのが下手くそでした。今もわかりやすい文章が書けている自信はありません。 それでも、これまでに何度か、議論が好転したり、プロジェクトが前に進むきっかけとなる文章を書けたことが
Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? パワポのスライドと箇条書きが人間を駄目にする 今から20年前の2003年、データの可視化やインフォメーションデザインの先駆者として有名なイエール大学の教授エドワード・タフティが「パワーポイントの認知スタイル」というエッセイを発表しました。 彼はこのエッセイの中で、パワーポイントのようなスライド形式はプレゼンテーション自体の質を低下させ、余計な誤解や混乱を招き、さらに言葉の使い方、論理的な説明、そして統計的な分析といったものが犠牲になるため、スライドをつくる人の思考回路にダメージを与えると主張します。 こうした主張に賛同する人は現在でも多
Obsidian がすごくいい
Obsidian（オブシディアン） と出会ってまだ3日目ではありますが、ここ最近で一番興味をそそられるアプリだったので紹介します。 A second brain, for you, forever. https://obsidian.md/ 出会いの経緯 を眺めていたときに一つの記事が目に付きました。 私がソフトウェア開発者として Notion から Obsidian に移った理由トップ3 何やら少し挑戦的なタイトルです。私も情報を整理するときに Notion はよく使用しています。不満がないとは言わないものの、Notion の機能を超える情報整理ツールは中々ないことくらいはわかります。 気になった記事は、まず読んでみることです。 読みながらの感想 "Obsidian" ……なんて読むの？ｶﾀｶﾀ……オブシディアン。いやー、スペルも読み方も覚えられないなぁ……。どんな意味なの？ｶﾀｶﾀ……
自分が良い Design Docs(Software Design Document)を書くために、読んだ/参考になったリソース集 一覧 Design Docs とは Design Docs at Google デザインドック(Design Doc)について デザインドックで学ぶデザインドック 残業も減らせる!? 上級エンジニアになるための Design Doc 超入門 「Design Doc」って何なのか？ What Is A Design Doc In Software Engineering? (full example) What is a Design Doc: Software Engineering Best Practice #1 https://github.com/kaiinui/note/blob/master/Design--Designdoc.md Googleの
たった5分の“文章力トレーニング”法。「部分書き写し」があなたの文章力を上げるワケ - STUDY HACKER（スタディーハッカー）｜社会人の勉強法＆英語学習
ビジネスパーソンのみなさんの中には、効果的な文章力トレーニングをさがしている、という方も多いのではないでしょうか。 文章は、仕事における重要なコミュニケーションツールです。メール、報告書、企画書など、1日のうちでも様々な文章を書く機会があります。 しかし、「文章をまとめるのが苦手」「相手に伝わらない」といった悩みを抱える方は少なくありません。そのために文章作成に時間がかかりすぎたり、意図が正しく伝わらず仕事に支障をきたしたりすることも。 そんな方におすすめなのが「部分書き写しトレーニング」です。優れた文章を書き写すことで、効率的に文章力を鍛えることができます。本記事では、このトレーニング方法の具体的な効果と、すぐに始められる実践手順をご紹介します。 文章力トレーニングに「部分書き写し」が効果的な理由 文章構造を理解できる 文章のリズムをつかめる 部分書き写しの具体的な練習ステップ 書き写し
はじめにTIG真野です。 秋のブログ週間2023 の3本目は、設計ドキュメントをGit管理して腐らせないようにがんばってみた話をします。 前段として6年前、「我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか」という記事を書いたのですが、その後の試行錯誤はどこにも残していないことに気づきました。普段のフューチャー技術ブログですとちょっと引け目を感じるテーマですが、秋の夜長を楽しむため読み物成分を多めに書くというテーマのこのブログリレーにピッタリな気がするため、この機会をお借りします。 ドキュメントも色々な種別があるかと思いますが、この記事では設計ドキュメントを指すことにします。設計ドキュメントは開発メンバーが参照するもので、ステークホルダーへの説明資料に引用して使うことはあれど、主目的は異なるという前提です。Design Docの場合もありますし、システム構成図、ERD、
2025.02.20 ITニュース フルリモートゆめみAI ゆめみが今年2月5日に公開した「原則出社」を打ち出すドキュメントが話題を呼んでいる。 コロナ禍により一気に進んだリモートワーク。さまざまな課題が見えてきたことで、国内外の企業が出社に回帰する流れが確かにある。 しかし、ゆめみはコロナ禍に突入するより前の2019年に「リモートワーク先端企業」を宣言。それ以降も社内外に対してエンジニアの働きやすさをアピールしてきた会社だ。 そのゆめみが「原則出社」を宣言するからには、背景には相当な課題意識と覚悟があったはず。宣言後には、社内でも相当なアレルギー反応があったことは想像に難くない。 そしてこのドキュメントに関して、内容と同じくらい話題になっているのが、「原則」と「メタ原則」からなる独特の言い回しだ。 今回の件の事情を赤裸々に語ってもらうべく、代表の片岡俊行さんにインタビューを実施した。 「
何かを調査している時など、人に聞いた方が早いかもしれないことはよくある。"かもしれない" というのがポイントで、もう少し自分で調べた方がいいかもという気持ちもちょっとあって判断がむずかしい。 経験上そういう時は聞いてしまったほうがよくて、聞くフレーズの引き出しを増やしておくと聞きやすくなる。自分が聞く時にチャットでも口頭でもよく使っているフレーズを雑にまとめてみる。 質問です！もしすぐわかったら教えてください いったん雑に聞いてしまうんですが もしもっと詳しい人や適切な人がいたら教えてください 何かこれを読むべしみたいな資料をもらえるだけでも助かります 以前に対応していたようなのでちょっと聞きたいんですが 頓珍漢な質問だったらすみません！ もしテキストだと説明しづらかったら、シュッとhaddleやzoomで話させてください 30分だけ時間もらって相談させてもらっててもいいですか。もしOKな
クラウドサービスでは大量の機能が多種多様に提供されており、簡単なアプリでも複数のサービスを組み合わせて利用することも珍しくありません。そうしたバックグラウンドのサービスを設計する際に役立つのがサービス間の構造を図に落とし込んだ「アーキテクチャ図」です。これまでもサードパーティーからさまざまなアーキテクチャ図作成ツールが提供されてきましたが、2022年2月17日にGoogleが自社クラウド向けの公式アーキテクチャ図作成ツールをリリースしたので、早速使い勝手を試してみました。 Google Cloud Developer Cheat Sheet https://googlecloudcheatsheet.withgoogle.com/architecture Introducing a Google Cloud architecture diagramming tool | Google Cl
文化審議会の国語課題小委員会は30日、半世紀以上前の通知に従い、公文書では読点に「，」（コンマ）を使うとのルールを見直し、一般に広く使われている「、」（テン）を用いるよう求める中間報告案をまとめた。年度内に正式な報告をまとめ、文化庁がその後に内閣官房と通知見直しに向けて協議する。 公文書は、1952年に当時の官房長官が各省庁の事務次官に通知した「公用文作成の要領」で、「なるべく広い範囲」で左横書きとし、横書きでは句読点には「。」（マル）とコンマを使うと定められた。ただ、現在は多くの省庁がテンを使っており、文化庁は要領改定を検討してきた。
Agile Manifestoには以下のように書いてあります。 動作するソフトウエアは包括的なドキュメントにまさる ともするとドキュメント軽視と取られかねない宣言です。この宣言を誤って解釈してドキュメントはいらないとなる場合もあるかもしれませんが筆者はそれは間違いだと思っています。この宣言では包括的なドキュメントよ
リリースノート管理術
みなさま、OSSの変更履歴、要するにCHANGELOGやリリースノートはどのように管理しておられるでしょうか。自分はというと、抱えるリポジトリも数百個に増えてきて、まあ要するに細かく管理するのがだるく、最近は変更履歴の管理方法も変わってきました。 CHANGELOGからGitHub Releasesへ 昔は、おおよそKeep a changelogの方式に準拠したCHANGELOG.mdを書いていました。semantic versioningでバージョン管理をしながら、個々のバージョンごとに次のセクションを設けて変更内容を説明するような感じです。 Added Changed Deprecated Fixed Removed Security 今は、新規につくるリポジトリではCHANGELOG.mdは用意せず、GitHub ReleasesにKeep a changelogに似た形式で変更内
文章を書く前にやることよい文章を書くには、実際に文章を書く前に、読者は誰か、どういう悩みを解決するのかを企画することが大切です。また、それを元にアウトラインを書いておきます。 このふたつを元に文章を書くことで、読みやすい開発ドキュメントにつながります。これについては、次の記事をご覧ください。 開発ドキュメントを書く前に決めるべき3つのこと【企画編】開発ドキュメントにおけるアウトラインの書き方開発ドキュメントの書き方企画とアウトラインの作成が終わったら、実際に文章を書いていきます。文章を書くときは、次の9つを意識して書きます。これだけで、読みやすさ、分かりやすさが大きく向上します。 一文を短く切る結論を先に述べる指示語を使わない主語を明確にする、述語との距離を近づけるひらく・閉じるを統一する再現条件を示す前提を揃える見出しや箇条書き、表などを適切に用いる読者に伝わる用語を使うひとつずつ説明し
こんにちは丸山@h13i32maruです。システム全体を簡単な図とテキストでまとめる「ARCHITECTURE.md」というものを最近知りました。これは良さそうと思い、JasperのARCHITECTURE.mdを書いてみました。 jasperapp/jasper/ARCHITECTURE.md ARCHITECTURE.md自体の目的は「プロジェクトへの新規参加者が全体像の把握を効率的に行えるようにする」という感じです。書き方の指針や注意点などは考案者による記事を見てもらうのがよさそうです。また良いサンプルとしてrust-analyzerというOSSのARCHITECTURE.mdが紹介されています。 https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html https://github.com/rust-analyzer/ru
RFCの読み方
こんにちは。技術開発室の伊藤です。 ハートビーツではメールサーバを自社で運用しています。そのメールサーバの移設を実施するにあたり、移設を対応するチームでさまざまなメールの仕様を理解しておく必要がありました。 メールプロトコルの仕様についてはRFC（Request For Comments）が発行されているため、メールに関するRFCを読んでまとめる勉強会を行いました。 その際にRFCを読むにあたって知っておくとよいことがいくつかあったので紹介します。 RFCとは RFCとはIETF（Internet Engineering Task Force）というインターネット技術の標準化を推進する団体やその他の団体が発行している、インターネット標準や技術提供の文書です。もともとは非公式な文書であることを明確にするため、Request For Comments（コメント募集）という名前にしていたようです
Diagram as Code
Diagram as Code6 different ways to turn code into beautiful architecture diagrams
Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article?
AWSのサービス説明がよくわからんすぎるので『AWS製カップラーメン』の紹介を書いてみた「ホットスタンバイされたH2O」
新たな文学の芽生えを感じ、流行ってくれんかなと思ったため。ホットスタンバイが文字通りなところで耐えられなかった。
AWS構成図おすすめツール - Qiita
AWSの構成図を作成する際に便利なツールを紹介します。 vscodeの拡張プラグイン「Draw.io Integration」です。 インストール方法 vscodeの左サイドにあるExtensionsをクリックし、検索窓にdrawと入力するとDraw.io Integrationが表示される。そして、Installボタンをクリックするとインストールされる。 作画ツールの表示 インストール後に新規ファイル作成ボタンを押し、 拡張子を.drawioにすると自動的にvscode上でdrawioの作画ツールが表示される。 これを使って簡単なAWSの構成図を描いていきます。 構成図 VPCを作成して、その中にパブリックサブネット、EC2インスタンス、インターネットゲートウェイを作成する。 使い方 AWSアイコンの追加 下部の+More Shapesを押すと、アイコンのセットが表示される。 ここからA
マニュアル作成の準備は、マニュアル作成の5W1Hの「What」で登場した「洗い出し〜対象業務の選定〜改善」の3段階を、さらに7つのステップに分けて下ごしらえします。 洗い出し ツリーで業務を俯瞰して見える化します。ツリーは周囲とすり合わせた後、リスト（表）にして情報を追加します。 対象業務の選定 洗い出した業務のなかから、マニュアル化する業務を選びます。 改善 マニュアル化する業務のプロセスを分解して、改善の視点で見直し、マニュアルの骨組みをつくります。 ステップ1 ツリーで業務を見える化する ツリーで全体を俯瞰する 準備の第1段階「洗い出し」はツリーの作成からはじめます。洗い出しの目的は、「業務の見える化」の先にある「マニュアル作成」の効果を高めることです。 ツリーは、樹木（ツリー）の形の図表です。モノやコトを、木が枝分かれするように分解して表わします。 ここでのツリーは、論理思考でおな
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
読みやすいドキュメントを書くために今日からできる7つのこと｜壮｜Masato Tanaka
自己流の手順書フォーマットを公開してみた | DevelopersIO
伝わる文章作成の基本を学ぶための記事・学習コンテンツのまとめ - Qiita
「してほしい」だけじゃない 漢字で書けるのに仮名にする言葉
ソフトウェアドキュメント作法 - maru source
英語が苦手な人が英文Writingを学ぶにあたっておすすめの本五選｜Yuki Nakazato
リーダブルテストコード / #vstat
もし「リーダブルコード」を弁護士が読んだら？ - MNTSQ Techブログ
安全安心にソフトウェア開発を行うためのDesign Doc導入ガイド｜面川泰明
画面仕様書への静的検査器を実装したらたくさんの欠陥を発見できた話 - DeNA Testing Blog
ハーバード大学で150年以上教えられる作文術「オレオ公式」とは？...順番に当てはめるだけで論理的な文章に
リモート開発を助ける「思いやりのある文章」の書き方 - ROUTE06 Tech Blog
パワポのスライドと箇条書きが人間を駄目にする - Qiita
【メモ】良いDesign Docs(Software Design Document)を書くためのリソース集
設計ドキュメント腐る問題、Git管理で運用してみた結果 | フューチャー技術ブログ
ゆめみ突然の「原則出社」宣言に社内は猛反発？ 代表の胸中と真の狙いとは - エンジニアtype | 転職type
人に聞いた方が早いかもしれない時に使っているフレーズ - Konifar's ZATSU
Google純正の構成図作成ツールが登場したので早速使ってみた
公文書の読点「，」から「、」に 半世紀以上前の通知変更へ ｜ 共同通信
プロダクト開発でドキュメントを書かないとどうなるか
開発ドキュメントの書き方！9つのコツ【エンジニア】
ARCHITECTURE.mdというものを書いてみた - maru source
脱ExcelしたいMarkdownテンプレート目次 - Qiita
マニュアル作成はじめの一歩。「因数分解ツリー」で業務の洗い出しをはじめよう | ZUU online
www.google.com
news.denfaminicogamer.jp
wi-clinic.com
anond.hatelabo.jp
www.raddarj.org
www.nikkei.com