EX FOUNDRYのプロダクト情報を更新する方法

情報の種類を分ける

EX FOUNDRYでは、同じ説明を複数の記事へコピーし続けないよう、情報の役割を分けています。記事を増やすこと自体を目的にせず、利用者が「このサービスは何か」「どう動くか」「何が変わったか」「どのように更新されているか」を、それぞれ別々に確認できることを目指しています。

• プロダクト記事：現在の目的、対象ユーザー、主要機能
• 技術構成記事：現在のアーキテクチャと、そう選んだ理由
• リリース記事：特定の時点で追加・変更した内容
• 運用記事：検証、公開、訂正、更新の手順

プロダクトの基本説明が変わったときは紹介記事を更新し、過去の変更を残しておく必要がある場合だけリリース記事へ記録します。技術構成記事には現在の構成と選択理由を置き、古い構成を歴史として残すときは、現在の方式と混同しないよう見出しや日付を付けます。運用記事には、更新前後の確認、訂正の扱い、問い合わせの流れといったサイト横断の情報を置きます。

プロダクト紹介の記事では、利用者が最初に知りたい機能と制約を優先します。技術構成の記事では、ライブラリ名を並べるのではなく、なぜブラウザ処理とAPI処理を分けたのか、なぜ静的配信やSSRを選んだのか、失敗時にどう振る舞うのかを説明します。リリース記事では、変更の対象、公開URL、既存利用者への影響を具体的に書きます。

更新時に確認すること

1. 実際のプロダクト画面とリンクが開くこと
2. 記事の技術構成が現在のリポジトリと一致すること
3. 入力データ、保存、ログイン、外部通信の説明が正しいこと
4. 料金、仕様、依存サービスに古い情報が残っていないこと
5. pnpm verify と静的HTML生成が成功すること

さらに、記事の本文に書いた主要機能を実際の公開ページで確認します。リンク先がトップページだけでなく該当する機能ページへ移動できるか、リンク先のサービス名が一致するか、スマートフォンでも本文と表が読めるか、記事分類と対象プロダクトが一覧の表示と一致するかを確認します。外部リポジトリへのリンクは、ブランチ名やドキュメントのパスが変わっていないかもあわせて確認します。

生成AIを使って文章を整理した場合も、実装と一次資料を確認してから公開します。記事上のAI補助表示は、下書きの出所を隠さないためのものです。生成AIが補った一般的な説明をそのまま事実として採用せず、リポジトリのREADME、architectureドキュメント、実際の画面、テスト結果と照合します。確認できない性能値、利用者数、対応範囲、将来計画については断定を避けます。

文量を増やす場合も、見出しを増やすだけでなく、入力例、処理場所、利用上の制約、エラー時の挙動、更新の確認方法など、読者の判断に使える情報を追加するようにしています。同じプロダクトの紹介記事と技術構成記事で共通する説明が必要なときは、要約にとどめて相互リンクし、内容の正本は一か所に寄せます。

誤りを見つけたら

誤りやリンク切れは、お問い合わせに記載したGitHub Issuesからお知らせください。公開Issueへ書く内容に秘密情報を含めないよう注意してください。

修正した場合は、記事の説明を現状に合わせ、必要なら更新日とリリース情報を追記します。リンク切れだけを直す場合でも、そのリンクが示していた機能や一次資料が変わっていないか確認します。古い記事を残す場合は、現在の仕様と異なる可能性があることをページ上で案内し、現行の説明へのリンクを目立つ場所に置きます。

記事を削除する判断も更新の一部です。別サイトと内容が重複する記事、現在のプロダクトと関係がなくなった記事、検証できない説明だけで構成された記事は、公開数を維持するためだけに残すことはしません。公開する記事は少なくても、実際のプロダクトと結びつき、利用者が確認できる情報を含んでいることを優先します。

この運用を続けながら、EX FOUNDRYをプロダクトの現在地と変更履歴を確認できる場所にしていきます。記事の内容だけで完結させず、実際に利用できるプロダクト、ソースコード、編集方針、問い合わせ窓口へつなげることで、サイトの情報を検証できる状態を保っていきます。