documentationlisted

# 技術ドキュメント作成ガイド - 誠実性第一 ## 【絶対厳守】実測データ・検証結果の扱い ### なぜ厳守すべきか 読者は以下のように受け取ります： ```markdown ❌ 「メモリ使用量: 1,240MB → 85MB（93%削減）」 → 読者の認識: 「著者が実際に測定した結果だ」 ❌ 「実測したところ、78%高速化しました」 → 読者の認識: 「著者が検証して確認した事実だ」 ❌ 「このプロジェクトで効果を実証しました」 → 読者の認識: 「実際のプロジェクトで使って成功した」 ``` **問題点:** - 実際には検証していないのに、検証したと受け取られる - 読者が「著者は嘘をついている」と感じる - 信頼性が完全に失われる - 技術者としての評判を損なう ## 最重要原則: 誠実性と正確性 ### ❌ 絶対にやってはいけないこと #### パターン1: 架空の具体的数値 ```markdown ❌ 悪い例: ## パフォーマンス改善の実測結果 実測データ: - Before: 処理時間 5.2秒、メモリ使用量 1,240MB - After: 処理時間 1.1秒、メモリ使用量 85MB - 改善率: 79%高速化、93%メモリ削減 ``` **なぜダメか:** - 具体的な数値（5.2秒、1,240MB等）を書くと「実測した」と受け取られる - 実際には測定していないのに、測定したように見える - これは**虚偽の情報** #### パターン2: 「〜したところ」「検証した結果」 ```markdown ❌ 悪い例: 実際のプロジェクトで検証したところ、パフォーマンスが大幅に向上しました。 測定した結果、メモリ使用量が90%削減されました。 本番環境で試したところ、レスポンスタイムが半分になりました。 ``` **なぜダメか:** - 「検証したところ」「測定した結果」は「著者が実際に行った」と読める - 実際にはやっていないことを、やったように書いている - これは**読者への欺瞞** #### パターン3: 曖昧だが誤解を招く表現 ```markdown ❌ 悪い例: このテクニックを使うと、メモリ使用量が大幅に減ります。 パフォーマンスが劇的に向上します。 処理速度が数倍になります。 ``` **なぜダメか:** - 「大幅に」「劇的に」「数倍」は具体性がないが、効果を保証しているように見える - 実際の効果は環境・データ・実装により大きく異なる - 読者が期待した効果が出ないと「嘘だった」と感じる #### パターン4: Before/Afterに具体的数値 ```markdown ❌ 悪い例: ### Before ```typescript const users = await fetchAll(); // 100,000件 // 処理時間: 8.3秒 // メモリ使用量: 1,240MB ``` ### After ```typescript const users = await fetchStream(); // 100,000件 // 処理時間: 2.1秒（74%改善） // メモリ使用量: 85MB（93%削減） ``` ``` **なぜダメか:** - コメントで具体的な数値を書くと「著者が測定した」と受け取られる - Before/Afterの比較に具体的数値があると、検証済みに見える - これは**検証していない情報の提示** ### ✅ 正しい書