タグ: #documentation

← すべての記事

• 理解がボトルネックだという主張とその循環 — 説明を生成した側が検証対象であるとき

  エージェントがコードを作る速度が人の読む速度を超えたとき何が残るかを扱った記事が議論を集めました。著者は検証のための理解から参加のための理解へ目標を移そうと提案し、3つの仕掛けを出します。ところがコメントで出た最も強い反論は、その説明自体をモデルが書くなら検証が成り立つのかという循環の指摘でした。提案された仕掛けのどれがこの反論に耐え、どれが耐えないかを切り分けます。

  2026-08-14 · 13 分で読めます #engineering-culture#code-review#developer-experience#documentation#ai-assisted-development

• 文書のなかのコードのスクリーンショットはいつから嘘になるのか — 画像をビルド成果物にする

  手で撮って文書に貼ったコードのスクリーンショットは、ソースのない成果物です。コードが変わっても画像はそのままなので、ある時点から静かに間違ったものを見せ始めます。goshotのようなCLIで画像をコマンド一行から生成すれば文書と一緒に作り直せるようになり、その瞬間に秘密の値の隠しとスタイルの統一までレビュー対象へ引き上げられます。何が確認できた機能で、何を私自身が実行していないのかも併せて書きました。

  2026-08-09 · 14 分で読めます #documentation#developer-tools#cli#ci#automation

• Diátaxisを四つのフォルダと誤解する理由 — ひとつの文書に二つのモードを混ぜるとなぜ崩れるのか

  Diátaxisは文書をチュートリアル・ハウツー・リファレンス・説明の四種類に分けます。ところがチームのほとんどはフォルダを四つ作ったところで適用を終え、肝心の問題はそのまま残ります。本当の失敗は分類ではなく、ひとつの文書のなかで四つのモードを混ぜるときに起きるからです。混ざるとなぜ崩れるのかを、フレームワークが根拠にする二つの軸から辿り直し、段落単位で判定する羅針盤と、今週すぐ回せる作業ループまで整理しました。

  2026-08-09 · 16 分で読めます #documentation#diataxis#technical-writing#developer-experience#information-architecture

• 顧客向けドキュメントを上手に書く方法 — 信頼を生むコミュニケーション

  提案書から障害報告まで、顧客に届けるドキュメントは信頼の器です。ドキュメント種類ごとの書き方、読者への配慮、明確さ、トーン、そして文書中の表現が契約上の約束になり得るという法的含意まで、実例とチェックリストで整理しました。

  2026-07-01 · 30 分で読めます #documentation#communication#writing#client#soft-skills

• ドキュメントでコミュニケーションする方法 — 何度も読み返される文章を書く ♪ 聞けます

  ドキュメントは協業と引き継ぎの中心であり、絶えず読み返されるからこそ丁寧に書く必要があります。目的と結論を先に置く構成、読者への配慮、非同期コミュニケーション、テンプレート、そして過剰なドキュメント化を戒める方法を扱います。

  2026-06-19 · 39 分で読めます #documentation#writing#communication#async#collaboration

• Word 生産性 — スタイル、ショートカット、長文書の自動化

  Microsoft Word のスタイル、ショートカット、目次や図表番号、キャプションと相互参照、ヘッダーとフッター、高度な検索と置換、校閲機能、差し込み印刷を活用して長いレポートを自動化する実践ガイドです。クリック数を減らし、書式を一貫させ、数十ページの文書をすばやく扱うワークフローを段階的にまとめています。

  2026-06-15 · 25 分で読めます #word#productivity#office#styles#shortcuts

• 文章で働く開発者 — デザインドック、ADR、そして説得するテクニカルライティング ♪ 聞けます

  文章力がシニアエンジニアのレバレッジである理由から、デザインドックとADRの実践テンプレート、レビューを通過するドキュメントの技術、悪い文章のビフォー/アフター、AIを書くことに活用する方法と限界まで。コードより先にドキュメントが評価される時代のテクニカルライティングガイドです。

  2026-06-12 · 39 分で読めます #technical-writing#design-docs#adr#documentation#career

• 静的サイトジェネレータ 2026 正面比較 — Hugo · Eleventy · Astro · MkDocs · Docusaurus · Mintlify · Starlight · Nextra · VitePress · Jekyll · Zola ディープダイブ

  Next.js と Vite の時代を越えても生き残った静的サイトジェネレータ — Hugo、Eleventy 3、Astro、MkDocs Material、Docusaurus、Mintlify、Starlight、Nextra、VitePress、Jekyll、Zola — を「コンテンツサイト」と「ドキュメントサイト」という二軸で正面比較する。ビルド速度、コンテンツモデル、検索、AI 連携、価格、移行コストまで。Gatsby は

  2026-05-14 · 31 分で読めます #static-site#ssg#hugo#eleventy#mkdocs

• 開発者ライティング完全ガイド: Design Doc、RFC、ブログ、書籍、カンファレンス発表まで (2025)

  Staff+ エンジニアの影響力の80%は、コードではなく文章から生まれる。GoogleのDesign Docテンプレート、Rust/Python/NodeのRFCプロセス、Julia Evans/Dan Luu/Stratecheryのブログ分析、O'Reilly/Manning出版プロセス、カンファレンスのCFPから本番発表までの実践。AI時代のライティングツール活用、韓国語 vs 英語ブログ戦略、Staff+ 昇進パケットの書き方

  2026-04-15 · 24 分で読めます #writing#design-doc#rfc#tech-blog#conference-talk

• 開発者のためのテクニカルライティングガイド：RFC、ADR、技術ブログ、APIドキュメント作成法

  開発者ライティングの全て！RFC（Request for Comments）、ADR（Architecture Decision Records）、APIドキュメント（OpenAPI）、README、CHANGELOG、技術ブログの書き方、ダイアグラム（Mermaid/PlantUML）、ドキュメンテーション文化まで。

  2026-03-24 · 30 分で読めます #technical-writing#documentation#rfc#adr#api-docs

• 開発者のための技術文書作成完全ガイド：READMEからADRまで

  READMEファイルからAPI文書、アーキテクチャ決定記録（ADR）まで、技術文書作成の完全ガイド。Diátaxisフレームワークと最新の文書化ツールについて学びます。

  2026-03-16 · 12 分で読めます #documentation#technical-writing#soft-skills#developer#api-docs

• 技術報告書作成ガイド：構造設計からデータ可視化、自動化まで

  ITエンジニアのための技術報告書作成完全ガイド。報告書タイプ別の構造設計、ピラミッド原則、MECEフレームワーク、データ可視化技法、マークダウンテンプレート、自動化ツールまで実践ノウハウをまとめます。

  2026-03-13 · 26 分で読めます #culture#report-writing#technical-writing#documentation#visualization

• ITエンジニアのための日本語技術文書作成法：仕様書・設計書・障害報告書

  日本のIT現場で必須の技術文書（仕様書、設計書、障害報告書）を作成する方法を学びます。各文書の構造、必須表現、敬語の使い方を実務例とともに整理します。

  2026-03-03 · 16 分で読めます #japanese#tech-writing#specification#documentation#business-japanese

• Technical Writing英語ガイド — 開発者のための技術文書作成法

  README、APIドキュメント、RFCの書き方から、明確な文章構造、開発者がよくする英語のミスまで、Technical Writingの核心をまとめます。

  2026-03-03 · 9 分で読めます #english#technical-writing#documentation#2026-03