2011年6月10日、Evernoteを使用開始。 2014年9月19日、有料プランに加入。 2024年3月23日、クソみたいなメールが届く。 プラン、廃止 いつも Evernote をご利用いただき、ありがとうございます。このたびは今後の Evernote 登録プランに関する変更についてご案内させていただきます。 お使いの Evernote アカウントは Plus から Personal に移行されました。Evernote Plus など、一般のお客様に数年間ご利用いただけなかった従来の登録プランが廃止となったためです。この変更により、Personal プランで利用可能な機能すべてをご利用いただけます。 今後はAnnualの登録プランが現在の Evernote Personal プランの料金 129.99 USD/Yearに合うように更新されます。この料金は次の更新日である2024/4/
小学生に教えるために編集者歴17年の父親が本気で考えた…｢きちんと伝わる文章｣を書く10のコツ ｢説明ができる｣とは｢生きる力がある｣ということ
「伝わる文章」とはどのようなものか 私はWEB媒体の編集者／ライターをかれこれ17年ほどやっている。日本語で情報を伝えるのが仕事だ。 ジャンルとしては長文の体験レポートを中心に扱ってきた。ライトな読み物で、書くのも簡単そうだと思われるかもしれない。いやいや、そうでもないのだ。それぞれのバックグラウンドを持ち観察力に優れた書き手が、五感をフルに使い数時間かけて体験取材をすると、情報量がとんでもないことになる。それを限られた字数で読者にわかりやすく伝えるのは、実は技術のいる作業なのだ。 また、私は特に編集部の中でも新人ライターを多く担当しており、書き慣れない人が書いた文章を一緒に直し、読み手に伝わる書き方をアドバイスする経験をずっと積んできた。 そんな私が、小学生の子供の中学受験によってあらためて「伝わる文章の書き方」を見つめ直すことになった。本稿ではその経験について少し語らせてほしい。
テクニカルライティングの基本を学べます。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 サイボウズの2023年度 新入社員向け研修の資料です。 Twitter：https://twitter.com/naoh_nak 2022年版（初版）：https://speakerdeck.com/naohiro_nakata/technicalwriting
アメリカの職場にいると、日本にいるときよりも身近でレイオフだとか、職を変えるというのを頻繁に見かける。先日もそういう場面があったのだが昔日本で働いていた時のことを思い出した。 ドキュメントを書く理由 日本のソフトウェア企業にいたときは、「納品物であるから」という理由以外にも、「人がいなくなったときに会社が困るから」という理由でもドキュメントを書くことが推奨されていた。しかし、少なくとも今の職場ではそんな理由でドキュメントを書くのは推奨されていないのに、なぜ問題にならないのだろうとふと思った。 うちのマネージャは、バディ制ににして、みんな休暇できるようにしようとは言っているが、多分本当に退職対策ではないと思う。 チームのメンバーが抜けたときも、「とても残念で、ワークロードをどうしようという問題はあるけど、彼女の門出を祝福しよう」言っていた。つまり、こちらでも「工数」は問題になるけど、「引継ぎ
みなさんこんにちは。 資料デザインのリサーチや分析に取り組むパワーポイントのスペシャリスト、パワポ研です。 いつも企業が出しているパワーポイントの分析結果などを紹介しているのですが、本日は良いパワーポイントが見れる場所とその理由を紹介します。 どこで見れるのかずばり、経産省のHPです。以下のURLより「委託調査報告書」を確認ください。ご存じの方も多いかもしれませんね。 トップはこんなページになっています。 トップ的なページこの中で、例えば「令和4年度分の掲載一覧（PDF形式：48KB）」を押してみましょう。 令和4年度分の掲載一覧こんな感じのリストがずらっと並べます。エクセルでも同じようなものがダウンロードできます。正直見づらいですが、このリンクの一つ一つが調査報告書になっています。 何ですごいのか数と質です。 数のすごさ 数については、パワーポイント形式以外（ワード）の報告書もかなり混じ
リモートワークで仕事をしていると、Slack や Teams といった何かしらのチャットツールでコミュニケーションを取ることが多い。そうやって仕事を続けていく中で「こう伝えたらよりスムーズに話が進んだかな...」という後悔は多々あり、日々試行錯誤を続けている。 そうやって試行錯誤を続けていく中である程度テキストコミュニケーションを取る上でのフォーマットが定まってきた気がするので、箇条書きでまとめてみようと思う。（随時更新予定） prefix （接頭辞）をつける文章の先頭にその文章の目的がわかるような prefix をつけて、何のためにポストしたかを一目で分かりやすくする。例えば以下のような prefix をつけることがある。 【質問】→ 相手の返信が欲しい時 【共有】→ 返信は不要だが、内容は把握しておいてほしい時 【メモ】→ 返信不要で、後から検索できるよう残しておきたい時 箇条書きする
社内ドキュメントはなぜ更新されないのか？情報の鮮度を最小限の運用負荷で維持する「イミュータブルドキュメントモデル」のススメ - KAKEHASHI Tech Blog
はじめに こんにちは。カケハシの各プロダクトを支えるプラットフォームシステムの開発チームでテックリードを担当しているkosui(@kosui_me)です。 プロダクト開発の世界では、明瞭な社内向けドキュメントを書くための方法が数多く提案されてきました。読者の中には、製品要求を明瞭にするためにPRD (Product Requirements Document、製品要求仕様書) を書き、プロジェクトの背景から全体の設計やその代案について明瞭にするためにDesign Docsを書き、アーキテクチャに関する意思決定の記録を明瞭にするためにADR(Architecture Decision Record) を書いてきた方も数多くいらっしゃると思います。 しかし、どんな素晴らしいドキュメントも、何故か更新されなくなります。新メンバーへのオンボーディングのためにインフラ構成図を検索したあなたが見つけた
インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。まずは、本書籍の概要について話します。 本セッションの対象者と、セッションのゴール 岩瀬義昌氏：ご紹介いただきました、岩瀬と申します。よろしくお願いします。『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』は、もともと『Docs for Developers: An Engineer’s Field Guide to Technical Writing』という洋書だったんですが、その翻訳をして、今回この機会をいただいています。 余談ですが、APC（株式会社エーピーコミュニケーションズ）さんが「カプセルト
メモアプリの知見のお返しにきた
去年の大晦日に「メモアプリの知見を貸してほしい」という増田を書いた者です。750超のブックマークと注目をいただきまして大変感謝しています。 https://anond.hatelabo.jp/20221230142549 あれから半年経過してみて自分の使うメモアプリが定まってきただけでなく、メモの意識およびスタイルに変革が生じました。これを、皆さんからお借りできた知見の「お返し」としてご報告したいと思います。 「中身に興味無いけどブコメしたいからブクマした」という人は、簡単に作れそうな激辛料理を教えてください。最近自炊が楽しいもので…中華ばっかりですが。 コメントが「メモの意識変革」をくれましたブコメは270件、増田のトラバは50件と膨大なアドバイスや激辛スナック情報を頂いて、まずは発見がありました。 ある人が「タラタラしてんじゃね〜よ は激辛？」と聞いてきた折に「自分は激辛とは思ってない
＜書くことが苦手な人でも「オレオ公式」を知ることで、誰でも論理的な文章がすぐに書けるようになる＞ ハーバード大学で受け継がれているライティングメソッドから生まれた「オレオ公式」。 書くことが苦手な人でも「オレオ公式」を知れば、論理的かつ説得力のある「伝わる文章」の達人になれる。 『作文宿題が30分で書ける! 秘密のハーバード作文』（CCCメディアハウス）の「第1章 ハーバード大生みたいに考える」より一部抜粋。 作文上手になるためのセンターピンをねらえ！ 以前『ニューヨーク・タイムズ』の記者が書いた『習慣の力』（チャールズ・デュヒッグ著、講談社）という本が、世界中で話題になりました。人間の習慣の秘密について著者の考えをまとめた本です。 この本の中で著者は、「ボウリングのセンターピンを1本倒すだけでほかのピンも次々と倒れていくように、まず、その人が変えたいと思うもっとも大きな習慣をひとつ変える
新しいプロジェクトに参加してローカル環境を作り始めると、何かとエラーに遭遇します。 また、設計や実装について開発者に相談したり、コードレビューを依頼することもありますね。 開発者が近くにいれば、（それなりに、程よいタイミングを見計らって）話しかけて、エラーの原因を調べてもらったり、設計方法をホワイトボードにスケッチしながら相談できますが、リモート開発ではそうはいきません。 リモート開発で成果を上げるためには、このブログのように何の装飾もインタラクティブ性もない文章で、自分の状況や相談したい事柄を正確に伝える必要があります。 とはいえ私は昔、「文章がわかりにくい」と毎日、毎日上司にフィードバックをもらうくらいには文章を書くのが下手くそでした。今もわかりやすい文章が書けている自信はありません。 それでも、これまでに何度か、議論が好転したり、プロジェクトが前に進むきっかけとなる文章を書けたことが
パワポのスライドと箇条書きが人間を駄目にする 今から20年前の2003年、データの可視化やインフォメーションデザインの先駆者として有名なイエール大学の教授エドワード・タフティが「パワーポイントの認知スタイル」というエッセイを発表しました。 彼はこのエッセイの中で、パワーポイントのようなスライド形式はプレゼンテーション自体の質を低下させ、余計な誤解や混乱を招き、さらに言葉の使い方、論理的な説明、そして統計的な分析といったものが犠牲になるため、スライドをつくる人の思考回路にダメージを与えると主張します。 こうした主張に賛同する人は現在でも多くいて、その典型的な例がアマゾンです。アマゾンではミーティングの前に文章形式の資料が配られ、ミーティングの最初の5分はそれぞれがこの配られたレポートを黙って読むことから始まるという話は多くの方も聞いたことがあるのではないでしょうか。（リンク） 実は、アマゾン
はじめにTIG真野です。 秋のブログ週間2023 の3本目は、設計ドキュメントをGit管理して腐らせないようにがんばってみた話をします。 前段として6年前、「我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか」という記事を書いたのですが、その後の試行錯誤はどこにも残していないことに気づきました。普段のフューチャー技術ブログですとちょっと引け目を感じるテーマですが、秋の夜長を楽しむため読み物成分を多めに書くというテーマのこのブログリレーにピッタリな気がするため、この機会をお借りします。 ドキュメントも色々な種別があるかと思いますが、この記事では設計ドキュメントを指すことにします。設計ドキュメントは開発メンバーが参照するもので、ステークホルダーへの説明資料に引用して使うことはあれど、主目的は異なるという前提です。Design Docの場合もありますし、システム構成図、ERD、
技術記事を書くまでのステップについて順にコツを解説していきます。 特に、技術記事を書きたくてもテーマ選定が難しい、文章が苦手だ、なぜか筆が進まない、うまくまとめられないといった方に読んで欲しい記事です。 一応、エンジニア歴としては数年以内のジュニアレベルの方を想定しています。 以下のように技術記事を企画して、書いて、公開するためのプロセスごとにちょっとしたコツをまとめています。気になるセクションだけでも読んでいただければ幸いです。 テーマを決めよう 対象読者を決めよう 章立てを決めよう 書こう タイトルを決めよう 【余談】技術記事を書く理由とは 筆者について QiitaとZennにて6年以上の記事発信経験があり、 Qiitaでは5,942Contributionsを記録、 Zennでは3,253Likesをいただいています。 テーマを決めよう コツ：テーマのカテゴリによって執筆のポイントや
「専門性が高い人になりたいですか？」 そう問われたら、多くの人が「はい！」と答えるでしょう。エンジニアやデザイナーのような専門職に限らず、ビジネスパーソンの多くも、「できることなら何らかの専門性を高めたい」と思っているはずです。 しかし、そもそも「専門性が高い」とはどういう状態を指すのでしょうか。どんな人になれば「専門家」だと評価されるようになるのでしょうか。それを突き詰めて考えることが専門性を高めるヒントになると思い、少し深堀してみました。 最後には、まだ実験中ですが、ChatGPTを活用して専門性を高める方法をご紹介します。 専門性と体系化の関係 辞書サイトのWeblioを見ると、専門性とは「特定の分野のみに深く関わっているさま。高度な知識や経験を要求されることや、その度合い」と書かれています。この定義に従うと、専門性には「特定の分野の高度な知識や経験」が必要だということになります。
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のサービスを、簡単
DB設計の共有で疲弊してない？dbdocsのすゝめ
DB設計の管理や作成に疲弊してません？こんにちは。ukmshiです。今日はDB設計の共有と管理に便利なツール、dbdocsについてお話しします。dbdocsを使えば、設計の可視化や共有がめちゃくちゃ簡単になるんです。今回は、その魅力と利点、そして実際の使い方について詳しく説明します。 dbdocsとは？ dbdocsは、コードベース（DBML）でDB設計を管理し、URLで共有することが可能なツールです。データベースのテーブル構造や関係性を可視化し、それを他のチームメンバーやステークホルダーと手軽に共有することができます。 DBMLについてはこちらを参考に dbdocsの利点 dbdocsの利点について詳しく見ていきましょう。 無料 まず最初に、dbdocsは基本無料です。コストを気にせずに利用できるので、チームの誰もがアクセス可能です。 コードベースで管理 dbdocsはコードベースでDB
宿泊開発チームでエンジニアをしている @kosuke1012 です。チームで ADR を書き始めて1年くらい経ったので、その感想を書いてみたいと思います。 この記事は 一休.comのカレンダー | Advent Calendar 2023 - Qiita の13日目の記事です。 ADRとは アーキテクチャ・ディシジョン・レコードの略で、アーキテクチャに関する意思決定を軽量なテキストドキュメントで記録していくものです。 出典はこちらで、 Documenting Architecture Decisions わかりやすい和訳は以下の記事が、 アーキテクチャ決定レコードの概要 | Cloud アーキテクチャ センター | Google Cloud アーキテクチャ・デシジョン・レコードの勧め | 豆蔵デベロッパーサイト アーキテクチャの「なぜ？」を記録する！ADRってなんぞや？ #設計 -
日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード / Architectural Decision Records
2023年7月27日「Developers Summit 2023 Summer」にて 「日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード」というタイトルで「ADR」について発表した資料です
背景 開発チームが抱えるよくある課題として システムが変化する一方でドキュメントは更新されず腐る メンバーの流入出によって口伝でかろうじて継承された知見も失われる 検索性が良くないと過去のドキュメントが気づかれず、同じような内容のドキュメントが新規量産される 後から参加したメンバーはどちらが正のドキュメントか分からず混乱する といったことが良くあります。 解決方法としては以下のように、GitHub＆ルールベースで管理するといった例があります。 future-architect.github.io また組織・システムが大きくなってくると認知負荷を低減するためにドメインで区切るような形でチームの分割が始まりますが、 異なるチームによってシステムが管理され、システムの依存関係を全て知っている人がいなくなる CxOレイヤが大規模イベント前に現状を把握したいときに都度時間がかかってしまう チームごと
最終更新日: 2024年02月27日(月) 1. ご挨拶 2. 本記事執筆のモチベーション 3. ワークショップを通じて得たフィードバック 3-1. Pains -過去抱えた/現在進行形で抱えている辛み- 3-2. Approaches/Solutions -Pains を解消するために取った方策や導き出した解決策- 3-2-1. えいやで場所を決め打ちしてしまう(e.g., GitHub Wiki + Google docs しか使わない) 3-2-2. 個人的に、2023/12/05時点で〜みたいな書き方を心がけている 3-3. Tips -効果的な手法- 4. オーディエンスからの反響 4-1. 気づきや学び・NEXT ACTIONS 4-2. プレゼンター(@hayat01sh1da)へのフィードバック 4-3. Slack での反応 5. おわりに 1. ご挨拶 初投稿となります
設計ドキュメント腐る問題、 Git管理で運用してみた 本当のところ 2023.12.5 真野隼記 ドキュメント管理を制する 陳腐化を防ぐための実践事例 Lunch LT
背景: dbtを使っていてもER図は欲しい! どうやってER図を生成するか どうやってER図を見やすくするか まとめ 背景: dbtを使っていてもER図は欲しい! dbtはモデル間のリネージなど可視化が得意なツールではありますが、万能なわけではありません。モデルの生成過程などはリネージで担保できますが、分析時に「どれとどのモデルがJOINできて、JOINする際のキーはこれを使って」というER図で扱うような可視化はディフォルトではできません。 DWHを作っている側からすると「このテーブルはあの辺のテーブルと一緒に使うと便利で、いつもあのキーでJOINして」というのが頭の中に入っていることが多いため、ER図がなくてもどうにかなることも多いでしょう。しかし、分析に慣れていない人や分析に慣れている人であっても、普段と異なるドメインのテーブルを触るときはER図が提供してくれる情報は有用です。ちなみに
git-schemlexとddl-makerを使ったDB migrationの紹介 / git-schemalex and ddl-maker migration #golangtokyo
インフラの環境構築を行ったときに、はい、環境です、と接続情報だけ顧客に提供したところで、そのまま受け取ってくれることはない。 ドキュメントはないんですか？。 何を作ったかを示すドキュメントとセットで初めて、プロにお金を払って仕事をしてもらった気持ちになる。今でも、ドキュメントを残せ、ドキュメントがないと今どうなっているかがわからなくなる、常に更新して最新にしよう、そんな掛け声は健在である。 このドキュメント、年々複雑さが増していると思う。というのも、IT関連のソフトウェアにしろクラウドにしろ、機能は増えるばかりだからだ。かつ、設定自体は年々洗練されており、デフォルト値で動くことも多い。たくさんの設定項目があるが、設定するのはほんの一部分である。 ドキュメントに何を残すべきか。設定値全てをドキュメントに書き込もうものなら莫大な量になる。一方で変更したものは少ししかない。このギャップが激しくな
ドキュメント執筆にもGit、ビルド、テストで再利用性や整合性を実現する「Writerside」、JetBrainsがプレビューリリース
Kotlinなどの開発元として知られるJetBrainsは、テクニカルドキュメントのための一連のツールを統合したドキュメントオーサリングツール「Writerside」のプレビューリリースを発表しました。 ソフトウェア開発においては、テキストで記述されたソースコードをGitでバージョン管理し、ビルドによって複数のソースコードを1つのアプリケーションへとまとめ上げ、コンパイルし、テストをして本番環境へのデプロイによりアプリケーションを公開します。 そしてこのプロセス全体を、さまざまな機能を備えたツールチェンを用いて自動化することで、ソフトウェア開発の効率を高めています。 一方で、例えばアプリケーションのチュートリアル、SDKやAPIのリファレンスドキュメントなどのドキュメントの制作過程においては、複数のファイルをフォルダにまとめ、手作業で目次のページとリンクさせることや、ソースコードのサンプル
プロダクトの価値を最大化する「言語化筋トレ」のすすめ / "Verbalizing muscle training” to maximize the value of products
EM Oasis #4での発表資料です。 https://emoasis.connpass.com/event/312868/ ■リンク LayerX Casual Night（2024/04/26, 2024/05/15） https://jobs.layerx.co.jp/casual-night
AWS Docs GPT
AI-powered Search and Chat for AWS Documentation
Web API設計時に使われ方の想定を添えると良い。けどより良いやり方を知りたい - valid,invalid
先日登壇したイベントにて、仕事で協業したモバイルエンジニアから「Web APIのドキュメントに使われ方の想定が添えられていてありがたかった」とフィードバックをもらった。 具体的にはX post (以下、tweet) に添付した画像のような感じで、Web API (以下、API) が呼び出される画面・タイミングの想定、レスポンスの使われ方の想定などをUIのスクショとともに記述する、というもの。 API設計時にこういう使われ方の想定を添えると認識揃えやすくてありがたい、とモバイルエンジニアに喜ばれました#B43_techtalk pic.twitter.com/XLB3g6fCLZ— ohbarye (@ohbarye) 2023年8月3日 他にもこんなのとか。 APIレスポンスの使われ方の想定を書いているようす このことについて思ったよりもイベント内外で反響があったので書く。 ドキュメントの
Terraform構成をビジュアライズできるツール Pluralithを使ってAWS構成図を自動作成してみる | DevelopersIO
CIに組み込むことで真価を発揮するツールかと思うので、Localは検証・実運用はCIといった使い分けをするのが良さそうです。 やってみた 今回はLocalで試してみます。 Pluralith CLIのインストール 利用にはユーザー登録が必要です。 以下のページからユーザー登録します。 Pluralith サインインができたら以下のページに遷移します。 Localで試したいため、Local Setupを選択します。 Download CLIでバイナリをダウンロードして、macの場合は以下のコマンドでcliを利用できるようにします。 mv pluralith_cli_darwin_amd64_v0.2.2 pluralith mv pluralith /usr/local/bin/ chmod +x /usr/local/bin/pluralith ブラウザで表示されているAPI Keyを使っ
【データ基盤チーム ブログリレー 3日目】 こんにちは、エンジニアリンググループの石塚です。 趣味は筋トレです。好きなトレーニングはレッグカールです。今年2023年の1月に第一子が爆誕し、毎日子供の笑顔に癒されております。一方であまり言い訳にはしたくはないですが、事実自分自身の自由に使える時間は少なくなったなと感じております。そんな中でもトレーニングの時間は作りたいので、24時間ジムに契約して妻と娘が寝ている早朝の時間にウホウホトレーニングをしている今日この頃であります。時間のありがたみをとても感じるようになりました。 これは仕事でも同様かと思います。有限な時間の中でタスクを取捨選択して価値ある成果を上げていく事が仕事では求められます。ドキュメンテーションはその価値ある成果につながる時間を増やす一助になるかもしれません。 この記事では、ドキュメンテーションの必要性について言語化します。改め
インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。さらに、ドキュメントの具体的な書き方と、フィードバックの収集について話します。前回はこちらから。 ドキュメントは「書き始める」ことが大事 岩瀬義昌氏：3章にいきます。時間的にあと15分ぐらいしゃべっても大丈夫かな？ 10分ちょっとしゃべれると思うので。（スライドが）あと70枚あるので、すごく速くいきますね（笑）。 ドラフトの執筆です。みなさんもドキュメントを書くじゃないですか。ちょっと胸に手を当てて（考えて）みると、ドキュメントを書く上で、一番難しいことは何だと思いますか？ （スライドを示して）書ける人は良いんですが、最初の人が1文字目を書き
インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。最後に、ドキュメントの品質測定について話します。前回はこちらから。 「優れたドキュメントとは何か」を定義する 岩瀬義昌氏：最後にもう1個だけ。今日は9章までしゃべりたかったので、これをあと5分でしゃべれればゴールですね。ドキュメントの品質測定について話していきます。 （スライドを示して）品質測定、このあたりのキーワードから、きっとエンジニアであれば1度は言われたことがあるんじゃないかという言葉はこれです。 「計測できないものは改善できない」という言葉があります。これはいろいろな引用元があるので（スライドの）後ろに画像を出していますが、計測した
ROUTE06では、GitLab Handbook*1を参考に、全社に関係する情報をハンドブックとして社内に公開しています。ハンドブックは2023年8月時点で383ページ*2あり、50人前後の組織規模の会社としては文章化に積極的なことが現れている数字だと思っています。 また、ハンドブックとは別に、プロジェクトごとのレポジトリでは技術選定や設計方針をADR*3で残していたり、参加したセミナーのレポートをGitHub Discussionsに書いていることからも、ROUTE06で働く人は文章を書くことが習慣になっていると感じます。 そんな中、ある日社内のSlackに一つの問いが投げかけられました。 ドキュメント文化というのは、たとえばマニュアルに書いてないから分からなかった・故になんらかの失敗が発生した場合、マニュアルに書いていなかったことが悪いみたいな考え方になるのでしょうか 社内のSlac
HTML HTMLの仕様策定には複雑な歴史があります。詳細は他の解説記事に譲りますが、簡単に述べるとW3CとWHATWGのダブルスタンダード状態が長い間続いていました。2022年現在はWHATWGによってLiving Standardとしてまとめられた仕様が実質的な標準となっています。Living Standardという名前が示す通り、バージョンはなくエディターによって随時更新されています。 CSS CSSの仕様はW3Cが策定しています。現在は、CSSとして1つの標準仕様があるわけではなく、数多くのモジュールに分かれて標準仕様の策定が進められています。草案、勧告候補などを経て勧告に至るプロセスと、Levelという概念で整理されたバージョン管理が特徴です。年に1度、SnapShotとしてその時点での標準化の概況が公開されています。 JavaScript JavaScriptは主にWebブラウ
JAWS DAYS 2024の発表資料です == 自身の持つ技術知識を、どのようにして一冊の本に変えることができるのでしょうか？ 本セッションでは、商業誌、技術同人誌、Amazon Kindle ダイレクト・パブリッシングを通じて出版した経験を生かし、技術書執筆の全過程を詳細に解説します。アイデアの見つけ方から、効果的な執筆方法、出版プロセスまで、具体的なテクニックをAWS本の執筆例を元に公開します。 このセッションを通じて、あなたの技術知識を価値ある技術書に変える第一歩を踏み出しましょう。
The future of tbls and "Documentation as Code" / phpconfuk 2023
https://fortee.jp/phpconfukuoka-2023/proposal/df1faefa-056a-493a-87d3-45934e96ea8c
PHPカンファレンス小田原2024の登壇資料です。 https://fortee.jp/phpconodawara-2024/proposal/56218b4f-b724-4199-82f1-67497501a9ef ADRとはなにか？ なぜ、導入する必要があるのか？ 実際に導入してみて苦労したこと 良かったこと、悪かったこと
日本語表記ガイドラインのすすめ
こんにちは、技術開発チームの滝澤です。 わたしは弊社のブログや資料などの文書に対して技術的観点からの確認を依頼されることがあります。しかし、内容以前に日本語表記の点で気になり、指摘することが多いです。それでは、どのような点に注意して文章を作成すればよいでしょうか。日本語表記についてのガイドラインや参考資料がウェブ上で閲覧できるので、それを利用すればよいです。本記事ではそのガイドラインや参考資料について紹介します。 なお、本記事は社内勉強会で発表した資料に加筆して再構成したものです。 まとめ 結論を先に述べると、日本語表記ガイドラインとしては次の資料が参考になります。 公用文作成の考え方（建議） JTF日本語標準スタイルガイド（翻訳用） 外来語（カタカナ）表記ガイドライン第3版 書籍『日本語表記ルールブック第2版』日本エディタースクール編 書籍『日本語スタイルガイド（第3版）』一般財団法人テ
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
さようなら、全てのエヴァーノート - 本しゃぶり
テクニカルライティングの基本 2023年版
アメリカの職場ではなぜドキュメントも無いのに人が去っても問題ないのだろう？｜牛尾 剛
【極上パワポの宝庫】経産省の委託調査報告書には、なぜ日本で一番きれいなパワポが集まるのか｜パワポ研
テキストコミュニケーションで意識していること｜ymdkit
「ドキュメントの書き方」を体系的に学んだことがないエンジニアへ 書籍『エンジニアのためのドキュメントライティング』の概要
ハーバード大学で150年以上教えられる作文術「オレオ公式」とは？...順番に当てはめるだけで論理的な文章に
リモート開発を助ける「思いやりのある文章」の書き方 - ROUTE06 Tech Blog
パワポのスライドと箇条書きが人間を駄目にする - Qiita
設計ドキュメント腐る問題、Git管理で運用してみた結果 | フューチャー技術ブログ
なかなかアウトプットできないあなたが技術記事を書くときのコツ
さて、専門性と体系化の話をしようか | knowledge / baigie
ADR を1年間書いてみた感想 - 一休.com Developers Blog
開発者ポータル Backstage とは - Carpe Diem
社内技術ドキュメンテーションを科学する - スタディサプリ Product Team Blog
20231206_設計ドキュメント腐る問題、Git管理で運用してみた本当のところ
dbtで見やすいER図を生成する - yasuhisa's blog
非同期開発体制を支えるドキュメント文化 / YAPC::Hiroshima 2024
ドキュメントの限界 - orangeitems’s diary
エンジニアリングの時間を生み出すドキュメンテーション術 - エムスリーテックブログ
ユーザーはドキュメントを「読みにくるけれど読んでいない」 “流し読み”しやすいドキュメント作成のポイント
優れたドキュメントは目的にかなっている “読む目的”を達成させるために書き手が意識したい「2つの品質」
ドキュメント文化を支える不文律 - ROUTE06 Tech Blog
HTML, CSS, JavaScriptの標準の仕様書はどこにあるのか
技術書を書く技術 JAWS DAYS 2024
ADRを一年運用してみた/adr_after_a_year