トポロジー図作成などに使ったりするアイコンは、結構サービス側で提供していたりする。 そう、よく目にするであろう、あのアイコンたちである。 リンクとともにまとめてみた。 Cloudサービス AWS AWSの公式アイコン集です。 2019/1/31からリリース2が公開されデザインが一新されました。PPT形式のドキュメントには、GroupsやIcons, Arrowsの使い方指南（すること、やってはいけないこと）が書かれています。このガイドにしたがって使いましょう。 また。この新しいバージョンの他に従来の旧バージョンも公開されています。 新バージョン 旧バージョン Google Cloud Platform 以前リンク切れていたのですがいつの間にか復活していました。アイコンが一新されたようです。 （ページには「図の例」があるよ、と言っているものの、2021/5/11現在まだ準備されていないようで
VP of Technology の星 (@kani_b) です。技術基盤や研究開発領域などを担当しつつ、社内の色々なことを技術の力でいい感じにする仕事をしています。セキュリティや AWS の話が好きです。 さて、みなさんは、ご自身が勤務する会社の就業規則を読んだことはあるでしょうか。 エンジニアに限らず、会社の全スタッフが仕事をする上で関わってくるのが、就業規則や情報セキュリティドキュメントなど、会社のルールや規程を記す文書です。 特にセキュリティやインフラに携わるエンジニアは、その改訂も含め携わったことがある方もいるのではと思います。 よくある文書管理 こうした文書は、以下のように管理されていることが多いようです。 ベースドキュメントは Word 保存時は PDF で保存 版管理は Word の編集履歴 + PDF に保存する際のファイル名 編集は担当部門, 担当者のみが行う かつての
Agile Manifestoには以下のように書いてあります。 動作するソフトウエアは包括的なドキュメントにまさる ともするとドキュメント軽視と取られかねない宣言です。この宣言を誤って解釈してドキュメントはいらないとなる場合もあるかもしれませんが筆者はそれは間違いだと思っています。この宣言では包括的なドキュメントよ
こんにちは丸山@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
Googleがコードレビューのガイドラインなど、ソフトウェアエンジニアリング実践のためのドキュメント「Google Engineering Practices Documentation」を公開
Googleがコードレビューのガイドラインなど、ソフトウェアエンジニアリング実践のためのドキュメント「Google Engineering Practices Documentation」を公開 ライセンスはクリエイティブコモンズの「表示 3.0 非移植 (CC BY 3.0)」で、複製や再配布、営利目的を含めた改変や翻案が可能になっています。 Googleで一般化されたエンジニアリングプラクティス Googleはこのドキュメントを次のように紹介しています。 Google has many generalized engineering practices that cover all languages and all projects. These documents represent our collective experience of various best practic
文章を書く前にやることよい文章を書くには、実際に文章を書く前に、読者は誰か、どういう悩みを解決するのかを企画することが大切です。また、それを元にアウトラインを書いておきます。 このふたつを元に文章を書くことで、読みやすい開発ドキュメントにつながります。これについては、次の記事をご覧ください。 開発ドキュメントを書く前に決めるべき3つのこと【企画編】開発ドキュメントにおけるアウトラインの書き方開発ドキュメントの書き方企画とアウトラインの作成が終わったら、実際に文章を書いていきます。文章を書くときは、次の9つを意識して書きます。これだけで、読みやすさ、分かりやすさが大きく向上します。 一文を短く切る結論を先に述べる指示語を使わない主語を明確にする、述語との距離を近づけるひらく・閉じるを統一する再現条件を示す前提を揃える見出しや箇条書き、表などを適切に用いる読者に伝わる用語を使うひとつずつ説明し
リリースノート管理術
みなさま、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に似た形式で変更内
Diagram as Code
Diagram as Code6 different ways to turn code into beautiful architecture diagrams
RFCの読み方
こんにちは。技術開発室の伊藤です。 ハートビーツではメールサーバを自社で運用しています。そのメールサーバの移設を実施するにあたり、移設を対応するチームでさまざまなメールの仕様を理解しておく必要がありました。 メールプロトコルの仕様についてはRFC（Request For Comments）が発行されているため、メールに関するRFCを読んでまとめる勉強会を行いました。 その際にRFCを読むにあたって知っておくとよいことがいくつかあったので紹介します。 RFCとは RFCとはIETF（Internet Engineering Task Force）というインターネット技術の標準化を推進する団体やその他の団体が発行している、インターネット標準や技術提供の文書です。もともとは非公式な文書であることを明確にするため、Request For Comments（コメント募集）という名前にしていたようです
「Markdownテンプレート」シリーズの目次です。 Markdownで全ての社内文書 GitHub Flavored Markdown推し 段落 Markdownで設計 Markdownでリリースノート Markdownで報告書 Markdownで職務経歴書 Markdownでスライド Markdownで会議 Markdownで校正 終わりに 以上、各記事が参考になれば幸いです。
AWSのサービス説明がよくわからんすぎるので『AWS製カップラーメン』の紹介を書いてみた「ホットスタンバイされたH2O」
新たな文学の芽生えを感じ、流行ってくれんかなと思ったため。ホットスタンバイが文字通りなところで耐えられなかった。
ビジネス資料のGitHub化ーーNotion2.0が目指す「テンプレ図書館」の衝撃 - BRIDGE（ブリッジ）テクノロジー＆スタートアップ情報
Almanacウェブサイト プログラミングをせずとも、ウェブもしくはモバイルアプリを直感的に構築できるノーコードサービス分野が成長してきました。「Bubble」や「AppGyver」のようなアプリ開発、日本の「STUDIO」や「Strikingly」に代表されるLP開発など、領域は様々です。ノーコードの本質は、時間やコストを圧倒的に削減することにあります。そして今、ノーコードトレンドの考えが新たな体験として企業で広く使われるドキュメント作成分野にも広がりつつあります。 「Almanac」は、ビジネスドキュメントテンプレートのクラウドライブラリを提供。マーケティング、人事、法務テンプレートなど、専門家によって公開された、磨き上げられた1万件の文書を提供しています。各資料をコピペすれば、ユーザーは手軽にプロのドキュメント内容をトレースできます。UIはノートツール「Notion」にとても似ていま
AWS構成図おすすめツール - Qiita
AWSの構成図を作成する際に便利なツールを紹介します。 vscodeの拡張プラグイン「Draw.io Integration」です。 インストール方法 vscodeの左サイドにあるExtensionsをクリックし、検索窓にdrawと入力するとDraw.io Integrationが表示される。そして、Installボタンをクリックするとインストールされる。 作画ツールの表示 インストール後に新規ファイル作成ボタンを押し、 拡張子を.drawioにすると自動的にvscode上でdrawioの作画ツールが表示される。 これを使って簡単なAWSの構成図を描いていきます。 VPCを作成して、その中にパブリックサブネット、EC2インスタンス、インターネットゲートウェイを作成する。 使い方 AWSアイコンの追加 下部の+More Shapesを押すと、アイコンのセットが表示される。 ここからAWS 1
マニュアル作成の準備は、マニュアル作成の5W1Hの「What」で登場した「洗い出し〜対象業務の選定〜改善」の3段階を、さらに7つのステップに分けて下ごしらえします。 洗い出し ツリーで業務を俯瞰して見える化します。ツリーは周囲とすり合わせた後、リスト（表）にして情報を追加します。 対象業務の選定 洗い出した業務のなかから、マニュアル化する業務を選びます。 改善 マニュアル化する業務のプロセスを分解して、改善の視点で見直し、マニュアルの骨組みをつくります。 ステップ1 ツリーで業務を見える化する ツリーで全体を俯瞰する 準備の第1段階「洗い出し」はツリーの作成からはじめます。洗い出しの目的は、「業務の見える化」の先にある「マニュアル作成」の効果を高めることです。 ツリーは、樹木（ツリー）の形の図表です。モノやコトを、木が枝分かれするように分解して表わします。 ここでのツリーは、論理思考でおな
（9月3日追記）元のタイトルは「行政文章はMarkdownで管理できるか」でしたが、ここで言っているのは「文章」ではなく、「文書」だろう、というご指摘をいただき、本文も含め訂正させていただきました。（追記終わり） 先日下記のTweetをしたところ、多くの人からコメントをいただきました。 行政文章のMarkdown化、進めていきたい。公開時だけでなく、普段からMarkdownでやりとりできるといいんだけどな。Wordを使って文章作ってる人をターゲットにしたMarkdownエディタを作ってみたい。 HackMDでもまだ難しいイメージ。実務に寄せていく必要がある。https://t.co/3iVDjXVHcQ — Hal Seki (@hal_sk) August 31, 2021 賛同の意見が多かったのですが、下記のような懸念点もいただきました。 ・編集する側も見る側も大変になる。何故やる必要
技術記事を書くまでのステップについて順にコツを解説していきます。 特に、技術記事を書きたくてもテーマ選定が難しい、文章が苦手だ、なぜか筆が進まない、うまくまとめられないといった方に読んで欲しい記事です。 一応、エンジニア歴としては数年以内のジュニアレベルの方を想定しています。 以下のように技術記事を企画して、書いて、公開するためのプロセスごとにちょっとしたコツをまとめています。気になるセクションだけでも読んでいただければ幸いです。 テーマを決めよう 対象読者を決めよう 章立てを決めよう 書こう タイトルを決めよう 【余談】技術記事を書く理由とは 筆者について QiitaとZennにて6年以上の記事発信経験があり、 Qiitaでは5,942Contributionsを記録、 Zennでは3,253Likesをいただいています。 テーマを決めよう コツ：テーマのカテゴリによって執筆のポイントや
分かりやすいドキュメントを書く「テクニカルライター」という仕事 / About the job "Technical writer" who writes easy-to-understand documents
もともとインフラエンジニアをしていた私が、LINEに入るまで知らなかった「テクニカルライターという職種があること」と「LINEにはテクニカルライティング専門のチームがあること」の2つについてお話しします。技術も好きだし、ドキュメントを書いたり、人に教えたりするのも好きだ、という方に「こういうキャリアもあるんだ」と発見してもらえるセッションです。 ■ 発表者 堀越 良子 / LINE株式会社 テクニカルライター。元インフラエンジニア。ねこが好き。 https://twitter.com/mochikoAsTech ■ セッション動画 https://youtu.be/nmFVXJGiCxM?t=2817 ※こちらは以下イベント内で発表した内容です https://line.connpass.com/event/205655/
「専門性が高い人になりたいですか？」 そう問われたら、多くの人が「はい！」と答えるでしょう。エンジニアやデザイナーのような専門職に限らず、ビジネスパーソンの多くも、「できることなら何らかの専門性を高めたい」と思っているはずです。 しかし、そもそも「専門性が高い」とはどういう状態を指すのでしょうか。どんな人になれば「専門家」だと評価されるようになるのでしょうか。それを突き詰めて考えることが専門性を高めるヒントになると思い、少し深堀してみました。 最後には、まだ実験中ですが、ChatGPTを活用して専門性を高める方法をご紹介します。 専門性と体系化の関係 辞書サイトのWeblioを見ると、専門性とは「特定の分野のみに深く関わっているさま。高度な知識や経験を要求されることや、その度合い」と書かれています。この定義に従うと、専門性には「特定の分野の高度な知識や経験」が必要だということになります。
設計とは、 要求（やりたいこと）をヒアリングする 要求を要件（何を満たさないといけないのか）に落とし込む 要件を実現するために考えられる手段を洗い出す 手段の検証を行う 検証結果を元に、どの手段を使うかを選定する 選定した手段を合意する（一部要件を満たさない事項がある場合は、代替策や妥協ラインについても合意する） 合意内容を元に、実装や設定に落とし込む をやることである。画面設計や機能設計のように、3-5の検証/選定が薄くなったり曖昧になったりするものはあるが、一般化するとこの流れになる。 設計書には、上記の設計でやってきたことを順番に書いていけばよい。これを文章構成のテンプレに落としていくと、 要求 要件 方式 対応案（いわゆる比較表で書いていくのが楽） 検証結果 選定・合意結果（合意した代替策や妥協ラインについても記載する） 詳細設計（どういう実装にするとか、パラメーターにするとか、細
この記事はGoodpatchアドベントカレンダー2022の23日目の記事です。 突然ですが、私は昨年「ナレッジマネジメント」領域の新規事業を立案し、リサーチや価値検証を行いました。結果としてはβ版を複数社に導入していただきながら行った価値検証を経てクローズという判断になってしまったものの、そのプロセスを通じて様々な組織におけるナレッジマネジメントの状況や課題感、そしてベストプラクティスまで多くの知見を得ることができました。 今回はそういった経験を土台として、これまで発信の主テーマにしていた「UXデザイン」や「サービスデザイン」の領域ではなく「ナレッジマネジメント」というテーマで記事を執筆することにしました。 この記事では、組織としてナレッジマネジメントを推進する時にどのような観点や考え方が必要なのかを紐解いていけたらと思います。 (組織の状況やカルチャー、事業形態などによっても最適なHOW
WEB+DB PRESSと私
「大江戸Ruby会議10」での発表資料です。 https://regional.rubykaigi.org/oedo10/
マイクロソフト、ChatGPTに任意のドキュメントを読み込ませて回答を得られる「Azure OpenAI Service On Your Data」パブリックプレビュー開始
マイクロソフトは、ChatGPTとChatGPT-4に任意のドキュメントなどを読み込ませることで、そのドキュメントに基づいた回答を自然言語で得られる新サービス「Azure OpenAI Service On Your Data」のパブリックプレビューを発表しました。 例えば、社内規約や社内マニュアルなどをChatGPTに読み込ませると、「PCの修理を申し込むための社内手続きは？」といった、汎用の知識だけしか持たない従来のChatGPTでは答えられない質問にも回答できるようになります。 さらに、ChatGPT/ChatGPT-4に任意のドキュメントを読み込ませるための支援ツール「Azure AI Studio」には、そのままチャットボットAIをWebアプリケーションとして公開する機能が備わっています。 これにより、ドキュメントやデータを読み込ませるように設定したチャットAIのサービスを、簡単
知らないWebアプリケーションの開発に途中からJOINしたとき、どこから切り込むか？ / PHPerKaigi 2020
https://fortee.jp/phperkaigi-2020/proposal/c8d6b9b1-29e4-48bd-b8bd-9f43f74d6265
ネットワーク構成図を考える: NW図の基本とモデル指向NW図のススメ / OSC_2020_Tokyo_Spring
OSC 2020 Tokyo/Spring でやる予定だったセミナーの資料です。 https://www.ospn.jp/osc2020-spring/modules/eguide/event.php?eid=44 残念ながらOSC東京春は今回は中止となってしまったのでとりあえず公開しておきます。
Home | DBML
Intro DBML (Database Markup Language) is an open-source DSL language designed to define and document database schemas and structures. It is designed to be simple, consistent and highly-readable. It also comes with command-line tool and open-source module to help you convert between DBML and SQL. Table users { id integer username varchar role varchar created_at timestamp } Table posts { id integer
概要 Design Documentと聞くと何を想像しますか？ 一般的にDesign Documentが指すのは設計書であることが多いのではないでしょうか。 設計書、簡単に説明するのであればソフトウェアを「どうやって作るの？」を説明したドキュメントです。 Googleではソフトウェアエンジニアリング文化における重要な要素として、今回お話ししていくDesign Docsと呼ばれるものがあります。 Design Docsとは？ Design Docsとは、開発者がコーディングに着手する前にソフトウェアシステムまたはアプリケーションの開発する人が作成するドキュメントです。 => ソフトウェア設計における仕様書や設計書とは別物と捉えた方がよいです。 仕様書、設計書は作成した上でのDesign Docsの作成となるようです。 このドキュメントには、高レベルの実装戦略と主な設計の決定事項がまとめられて
LINEの社内には「テクニカルライティング」の専門チームがあります - LINE ENGINEERING
こんにちは、Developer Contentチームのmochikoです。LINE株式会社でテクニカルライターとして働いています。今日は「テクニカルライター」というお仕事と、LINEにあるテクニカルライティングの専門チームについてお話しします。 テクニカルライターという職種があります テクニカルライターって何をしてるの？何を書くの？ ドキュメントはどうやって書いてるの？ どんなメンバーで仕事をしてるの？ ドキュメントを書く以外にこんなこともしているよ でもドキュメントを書くだけだと技術力が下がらない？ どんな人がテクニカルライターに向いてるの？ テクニカルライターという職種があります 私はもともとウェブ制作会社のインフラエンジニアでした。とある技術書を書いたことをきっかけに「テクニカルライターとして一緒に働きませんか？」と声をかけてもらい、LINEへ転職するに至ったのですが、実はお誘いをい
こんにちは、製造業でソフト開発エンジニアをやっているとみー(@tommyecguitar)です。 会社で納品物の説明ドキュメントを作ることがあり、その時にMarkdownでの組版をやってみたので、どう運用したか、困ったところ、いい点、悪い点をまとめてみようと思います。 Vivliostyleで組版したブログはたくさんあるので、見た目がどんな感じにできるかなどはそちらを見ていただくか、Vivliostyleのサイトをご覧ください。 Wordじゃだめなのか。 製造業で何かしら長大なドキュメントを作るとなったら、大抵はWordを複数人数で編集するという運用をしているところが多いと思います。 しかし、Wordにはいろいろと悪いところがあります。 チーム内で共同編集すると、編集したところが消えたり、フォントやデザインがなぜか統一されなかったりする。 セクションごとに担当を分けても、マージが手作業にな
みなさんテストは書いていますよね. 書いていなければふりだしに戻る. 例えば関数 add に対して, 以下のようなテストコードがあるとします. describe("add", () => { it("正しく計算できる", () => { expect(add(1, 2)).toBe(3); }); }); よさそうですね? もしよくないと思うのであればここから下は読まなくても大丈夫なくらい理解している方だと思います. 続いて関数名を変えただけのこちらをどうぞ. describe("sub", () => { it("正しく計算できる", () => { expect(sub(1, 2)).toBe(3); }); }); なんだか明らかに間違っている気がします. もしこのテストが通過してしまったとき我々はどうすればよいのでしょうか. 考えられるパターンは 2 つあります. 実装もテストも正
DB設計の共有で疲弊してない？dbdocsのすゝめ
DB設計の管理や作成に疲弊してません？こんにちは。ukmshiです。今日はDB設計の共有と管理に便利なツール、dbdocsについてお話しします。dbdocsを使えば、設計の可視化や共有がめちゃくちゃ簡単になるんです。今回は、その魅力と利点、そして実際の使い方について詳しく説明します。 dbdocsとは？ dbdocsは、コードベース（DBML）でDB設計を管理し、URLで共有することが可能なツールです。データベースのテーブル構造や関係性を可視化し、それを他のチームメンバーやステークホルダーと手軽に共有することができます。 DBMLについてはこちらを参考に dbdocsの利点 dbdocsの利点について詳しく見ていきましょう。 無料 まず最初に、dbdocsは基本無料です。コストを気にせずに利用できるので、チームの誰もがアクセス可能です。 コードベースで管理 dbdocsはコードベースでDB
PlantUML で JSON データを簡単視覚化
最近，仕事で使うことがあってたまたま気がついたのだが， PlantUML って JSON や YAML のデータを視覚化できるんだね。 やり方は簡単。たとえば { "firstName": "John", "lastName": "Smith", "isAlive": true, "age": 28, "address": { "streetAddress": "21 2nd Street", "city": "New York", "state": "NY", "postalCode": "10021-3100" }, "phoneNumbers": [ { "type": "home", "number": "212 555-1234" }, { "type": "office", "number": "646 555-4567" } ], "children": [], "spous
公式ドキュメントの読み方
「公式ドキュメントを読め」というのが急に話題になっていたので自分なりに整理してみました。 注意: そんなに真面目に推敲していません。フィーリングで書いているので実態に即してない部分もあるかも…… 公式ドキュメントとは何か あなたが使おうとしている道具 (ライブラリ、フレームワーク、プログラミング言語、ミドルウェア、コマンドラインツール、etc.)[1] は必ず誰かによって作られています。ある程度成熟した道具であれば通常、その作った人・組織自身によって公開されているドキュメントがあるはずです。これが公式ドキュメントです。 公式ドキュメントは、OSSにおいてはソースコードと双璧をなす最も信頼できる資料のひとつです。ソースコードが非公開の場合は通常、公式ドキュメントが最も信頼できる資料でしょう。 (以降はOSSを主に想定して説明します) たとえば…… Python のソースコードはGitHub上
初めて「論文」を書こうとしている人向けの、主にメンタル面（気持ち）の対処をメインにした書き方の指南書。 （ただし、メンタル面だけでなく書き方全般についても説明しています。） 筆者が査読付き論文を書くときに経験した最も大変だった（辛かった）ことは、研究の中身や書き方自体ではなく、諦めずに論文を書き上げて提出しようという意思を保ち続けること、つまりモチベーションの維持でした。モチベーションの維持は、個人の気持ちの持ちようとして片付けられがちに感じます。しかし対処方法は少しながらあるように思うのです。 本資料が、論文書きを諦めてしまおうとしている、あるいは諦めてしまった過去がある人への励ましになることを期待しています。 （10/6追記：本資料内での「レビュアー」は、自分が書いている原稿を添削指導してくれる人のことを指しています。しかし一般的にはレビュアーとは査読者のことを指す場合が多いのでちょっ
Big Sky :: Microsoft Word を Markdown に変換するコマンド「docx2md」を作った。
8月に Google Developers Expert となり、新米の様にオロオロとしています。過去の GDE ミーティングの議事録を見せて頂いているのですが Google Document に保存されており、Go だけでなく他のカテゴリの GDE に関する物も含めると全てに目を通すのはなかなか骨が折れます。技術者なので問題は技術で解決すべく、これらの資料を grep 検索できる様にしました。 Google Document はエクスポートすると Microsoft Word の形式となるので、Microsoft Word から Markdown に変換するプログラムを書けばテキスト検索もできるし、なんならそのまま GitHub に貼り付けてしまう事もできます。 GitHub - mattn/docx2md docx2md Convert Microsoft Word Document
“けしからん”天才プログラマーはなにを考える？ 登大遊氏を形成した歴史と日本のこれから けしからん本屋とけしからん大人たちが僕を育てた 天才プログラマー登大遊氏をかたちづくった「あの本屋」 例えば自分がエンジニアを目指したとき、どのように視野を広げればいいのか、漠然と不安を抱えたことはありませんか。そんな時、自分とは異なる“天才”の頭の中はどうなっているのか、その中身を覗いてみたいと思いませんか？ そこで今回は、天才プログラマーとしても知られる登大遊氏に、その考え方や思想の根源がどこにあるか、ちょっと頭の中を覗かせてもらいました。まずは、登氏がプログラミングに出会った幼少期について。 雑誌やマニュアルを読んで学んだ幼少期 ーーまず、登さんの幼少期についてお尋ねします。登さんは、小学生2年生の頃に自宅にあるPCでプログラミングをはじめたとのことですが、当時はどのように勉強されていたのでしょう
医師は情報が詰めこまれたスライドが好き？こんにちは、株式会社CureAppデザイナーの小林です。精神科の医師ですがデザインが好きすぎてデザイナーとして働いています。 医療の世界から会社員に転身すると、日々さまざまな発見があります。先日社外の人とプレゼンテーションの話題になり 「医師向けのプレゼンでは、シンプルなものより情報が詰め込まれたスライドが好まれるんです」 と言われ驚きました。 たしかに医療系のスライドは医師に限らず文字が詰めこまれた分かりづらいスライドが主流ですが、それはデザインへの関心が低いだけでけっして「好き」なわけではない、そう思っていました。 しかし改めて「もしかして医師は本当に複雑なデザインが好きなんじゃないか？」という疑念がわいてきました。 よく見る医療系スライドの一例 https://www.dinf.ne.jp/doc/japanese/resource/kouse
開発プロジェクトに新しく加わった時は、まずプロジェクトの理解が第一。しかし、全体像を把握できるようなドキュメントがなく、コードから断片的な情報をかき集めるしかない場合もあります。新参の開発者がスムーズにプロジェクトを理解できるよう、大規模なプロジェクトでは「プロジェクト全体のアーキテクチャ」を示した「ARCHITECTURE.md」を添えた方がよいと、エンジニアのAleksey Kladov氏が指摘しています。 ARCHITECTURE.md https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html Kladov氏はオープンソースプロジェクトの開発に携わる中で、「プロジェクトのアーキテクチャに対する知識量」によって開発スピードに大きな差が生じると気づいたとのこと。アーキテクチャに関する知識がない開発者にとって、大量のコードは「バラ
gRPCを用いたマイクロサービスのAPI仕様の記述 - Mercari Engineering Blog
この記事はMERPAY TECH OPENNESS MONTHの10日目の記事です。 こんにちは、メルペイのバックエンドエンジニアの柴田（@yoshiki_shibata）です。 メルペイのバックエンドは、Google Cloud Platform上でGoogle Kubernetes Engineを使用して、マイクロサービスアーキテクチャを採用した多数のマイクロサービスから構成されています。モノリシックなサービス実装では複数層のライブラリ（あるいはコンポーネント）から構成されるのに対して、マイクロサービスアーキテクチャでは複数層のマイクロサービスから構成されます。 どちらのアーキテクチャにおいても、偶発的プログラミング（Programming by Coincidence）1を避ける2ために、注意を払って作成する必要があるのが、境界部分のAPI（Application Programmi
ER図の作図について、 Draw.io, PlantUML, Mermaid を比較してみる。（VSCode拡張機能など） - Qiita
※ 参考記事「PlantUML を VSCode で利用したいけど、プレビューが表示されずエラーが出る」 参考（PlantUML 導入後の編集中画面） 2-2. ER図 今回作成したER図 Qiita記事でも、コードブロック内でPlantUMLの構文がそのまま使えます。（このER図は、Qiitaのコードブロックで表示させています） 今回作成したER図のPlantUMLの表記 @startuml yonde ' hide the spot hide circle ' avoid problems with angled crows feet skinparam linetype ortho entity "families" as families { id -- name nickname introduction created_at updated_at } entity "users
ドキュメント駆動開発v2
前提 ここで言っているドキュメントは仕様書ではなく、顧客向け製品ドキュメント。 ミドルウェア製品を開発 小さなチーム パッケージ製品とパッケージ製品のクラウド版 そのため顧客に提供するドキュメントが必ず必要 GitHub を利用 自分で開発する場合のフロー 作りたい機能をぼんやりでいいので GitHub Issue に追加する feature ブランチを切る デザインドキュメントをリポジトリの doc/ 以下に書く デザインドキュメントに合わせてコーディングを進めてなんとなく動くところまで作る 動かなくてもいいのでイメージを膨らませるためにコードを書いてみる デザインドキュメントは書き捨て前提で、とにかくメモを書く 製品ドキュメントを書き始めて、一旦書き終える ブランチマージに向けてコーディングを進める 書ける範囲でテストを書く ドキュメントを平行して修正する プルリクエストをだしてレビュ
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
ネットワーク図・システム構成図作成に使えるアイコン集 - Qiita
Markdown と GitHub で社内規程を便利に管理 - クックパッド開発者ブログ
プロダクト開発でドキュメントを書かないとどうなるか
ARCHITECTURE.mdというものを書いてみた - maru source
開発ドキュメントの書き方！9つのコツ【エンジニア】
脱ExcelしたいMarkdownテンプレート目次 - Qiita
マニュアル作成はじめの一歩。「因数分解ツリー」で業務の洗い出しをはじめよう | ZUU online
行政文書はMarkdownで管理できるか｜Hal Seki
なかなかアウトプットできないあなたが技術記事を書くときのコツ
さて、専門性と体系化の話をしようか | knowledge / baigie
設計書には何を書くべきなのか - terurouメモ
ナレッジマネジメントを組織に定着させるための提案｜國光俊樹
GoogleのDesign Docsから学ぶソフトウェア設計 - Qiita
納品ドキュメントの作成にMarkdown+Vivliostyleを採用した話 - Qiita
テストの説明に安易に「正しく」とか書かない - Object.create(null)
論文の書き方 - 主にメンタル面の対処を中心として
けしからん本屋とけしからん大人たちが僕を育てた 天才プログラマー登大遊氏をかたちづくった「あの本屋」
医師とデザイン。なぜ医療現場は複雑なUIが好まれるのか？｜Kei Kobayashi｜note
プログラムの「アーキテクチャに関するドキュメント」は面倒でも書くべき、ではどのように書くべきか？