googleドキュメントにmermaid.jsを書く - なおしむ論
googleドキュメントはオンライン上で編集できてとても便利 そこにmermaid.jsも書きたい！ってことでやってみた ドキュメントを書く こんな感じ これを読み込んでHTMLのページ上に図を表示します スクリプトエディタでプログラムを書く ツール > スクリプトエディタでエディタを開いてプログラムを書きます //ドキュメントのID var DOC_ID = 'YOUR_DOCUMENT_ID'; // HTMLを表示する function doGet() { return HtmlService.createTemplateFromFile("index").evaluate(); } // ドキュメントの内容を取得する function getDocs() { var docs=DocumentApp.openById(DOC_ID); return { title: docs.ge
持続可能なデータベースドキュメント生成 | メルカリエンジニアリング
この記事は Merpay Tech Openness Month 2022 の17日目の記事です。 はじめに こんにちは。Credit Design Teamでバックエンドエンジニアをしている@tk8です。主にメルペイスマート払いに関わるマイクロサービスの開発や運用をしています。 この記事では、私のチームでの持続可能なデータベースドキュメントへの取り組みに関して紹介します。 背景 私が担当しているマイクロサービスでは歴史的経緯（*1)もあり複雑なスキーマ設計をしています。また、領域的にドメイン知識が複雑なものも多く、バックエンドエンジニアでもデータとスキーマの関連に関して理解が難しいことが多々ありました。 さらに私のチームではQAエンジニアやPMもデータベースに関するドキュメントを読むことがあり、不明点があれば都度詳しそうな人に聞いたり過去のSlackでの会話を調べたりするなど非効率な状態
Documenting Architecture Decisions
Context Architecture for agile projects has to be described and defined differently. Not all decisions will be made at once, nor will all of them be done when the project begins. Agile methods are not opposed to documentation, only to valueless documentation. Documents that assist the team itself can have value, but only if they are kept up to date. Large documents are never kept up to date. Small
アーキテクチャの「なぜ？」を記録する！ADRってなんぞや？ - Qiita
5月のThoughtWorksのTechnology RadarでもADOPTされたADRという手法について、面白かったので、ざっくり自分なりに調べたメモです。 Technology Radarでは以下のように述べられています。 多くのドキュメントは、読みやすいコードとテストに置き換えることができます。しかし、進化的アーキテクチャでは、将来のチームメンバーの利益と外部の監督のために、特定の設計上の決定を記録することが重要です。Lightweight Architecture Decision Recordsは、重要なアーキテクチャー決定を、そのコンテキストおよび結果と共に取り込むための技法です。これらの詳細は、WikiやWebサイトではなくソース管理に格納することをお勧めします。そうすれば、コードと同期したままのレコードを提供できるからです。ほとんどのプロジェクトでは、この手法を使いたくな
Architectural Decision Records | adr.github.io
Architectural Decision Records (ADRs) An Architectural Decision (AD) is a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on the architecture and quality of a software and/or hardware system. An Architectural Decision Record (ADR) cap
社員ブログを頑張りたいけど、書くのがしんどい人に。いい記事書くためのブログ9選｜てらみ
こんにちは、てらみです！ ひと昔前はWebディレクターを名乗っておりましたが、最近はスタートアップ企業で採用広報をしております。 さてみなさん、会社からこんなお願いされてませんか？ 「入社エントリー書いてよ！」 「社員ブログ書いてよ」 「社員ブログ、今月中に書けないかな？」 ええ、わたしも日々このようなお願いを会社のみなさんにさせていただいてご飯を食べております。 お願いをしていると、「ブログを書いたことがない」「文章を書くのが苦手」「伝えたいことを上手く書けない」「書いてもあまり反応がない」と、三者三様、様々に文章を書くことに苦手意識をもっている方も多くいるようです。確かにな、その気持ちは結構わかります。 社員ブログがしんどいは、テクニックを知れば楽になるわたしも、かつては社員ブログの権化のような企業でブログ発信をしていました。在籍時の記事はこちら。2年いたけど、7本程度ですね。あまり多
並列構文を使いこなして分かりやすい文章を書く | プロフェッショナルライティングガイド
「並列表現」で文をわかりやすくする 場面に応じて「並列表現」を活用することで、理解しやすい文を書くことができます。並列表現は、文法的に同じ構成を繰り返します。同じ文法構成の文章の場合もあれば、箇条書きの場合もあります。並列表現を使うことで、文のリズムをよくして長文でも読みやすい構造にすることができます。 ニューヨーク市立大学リーマン校の教授であったチッヒー氏は「文を強調する有力な方法は並列化である。並列になる考えは同じ文法構造を取る。同じ文法構造を繰り返すことは、長文を読みやすくするもっとも効果的な方法である」と指摘しています[*出典]。 並列にするためには、以下の方法があります。
「Docs for Developers」を読んだ - 勘と経験と読経
最近知った興味深いPodcast e34.fm で紹介されていたので興味を持って読んでみた本「Docs for Developers: An Engineer’s Field Guide to Technical Writing」に関するメモ。 2023/3追記：翻訳されたようだ。ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング e34.fmwww.oreilly.com この記事の目次 「Docs for Developers」はどんな本なのか 全般的な感想 各章に関する覚え書き Front Matter Chap 1. Understanding your audience Chap 2. Planning your documentation Chap 3. Drafting documentation Chap 4. Editing docum
せめてリポジトリの各ディレクトリの概要説明だけでも欲しい思ったので dirmap というツールを作ってみた - Copy/Cut/Paste/Hatena
既存の開発に参加するときや、0->1の開発をしているとき、いつも「せめてリポジトリの各ディレクトリの概要説明だけでも欲しい」と思っていました。 既存のプロジェクトに参加するときは「プロジェクトの理解をする側」、0->1のプロジェクトで開発をしているときは「説明をする側の立場」で、です。 Ruby on Railsのような基本のディレクトリレイアウト決まっていてもそのプロジェクトの独自性がでてきますし、Goのようにスタンダードなレイアウトがないのであればなおさら初見ではわかりません。 「じゃあREADME.mdにでも書いておけばいい」というのはその通りです。 ただ、概要説明であっても一度書いたら終わりではなく、更新は必要になります。特に0->1のプロジェクトの初期ではディレクトリレイアウトすら途中で変わるということはままあります。 （ここらへんは「継続的ドキュメンテーション」として私の興味の
さまざまなグラフを帳票に表示できる「ActiveReportsJS」のチャート機能
本連載では、WebブラウザのJavaScriptで帳票を出力できるグレープシティのライブラリ「ActiveReportsJS」を活用した帳票アプリの開発を、複数回に分けて紹介しています。前回はTablixレポートコントロールを利用してデータのクロス集計を行う方法を説明しました。今回はさまざまなグラフを帳票に表示できるChartレポートコントロールの利用法を紹介します。 はじめに グレープシティのJavaScriptライブラリ「ActiveReportsJS」は、サーバー側処理ではなく、WebブラウザのJavaScript処理で帳票を出力できるライブラリです。本連載では、ActiveReportsJSの活用法を複数回に分けて紹介しています。 グラフを帳票に表示すれば、データを視覚的に把握できる、表現力豊かな帳票を作成できます。ActiveReportsJSでは、グラフを表示するChartレポ
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
xv6: シンプルで Unix 風な 教育用オペレーティングシステム
テクニカルライティングの基本 2023年版
GitHub - schemaspy/schemaspy: Database documentation built easy
GitHub - pseudomuto/protoc-gen-doc: Documentation generator plugin for Google Protocol Buffers
GitHub - joelparkerhenderson/architecture-decision-record: Architecture decision record (ADR) examples for software planning, IT leadership, and template documentation
Spotifyのアーキテクチャ決定レコード