developer-troubleshooting-docs

Export tickets, issues, and search logs, then cluster them by failure using the bundled error-cluster.py script which normalizes variable parts like paths and IDs. Rank clusters by reader-hours unblocked per writing hour, then write six-part entries covering message, applicability, cause, fix, confirmation, and escalation.

An error reference entry needs six parts in order: the verbatim error message in a fenced block, an applies-to section naming versions and platforms, the cause, numbered fix steps branched per cause, a confirmation signal proving the fix worked, and an escape hatch saying where to escalate and what to attach.

Skip pages for regressions introduced by a recent release, failures the next release eliminates, and problems readers cannot fix themselves like account suspensions. Also escalate failures recurring across multiple postmortems to a product fix instead of documenting around a defect.

No. Google restricted FAQ rich results to well-known government and health sites in 2023 and later removed the result type entirely, so FAQPage markup on troubleshooting content buys nothing. Put the error string verbatim in the title, first heading, and body instead.

Generate the catalog from one machine-readable source that both the product and docs read, as PostgreSQL does with errcodes.txt and Rust does with rustc_error_codes. Hand-synced catalogs drift by default; generation removes the failure mode rather than policing it.

Usually a findability problem: the error string is not verbatim on the page, entries sit on one mega-page where only one can win a query, or a retrieval-based assistant serves a stale index. Re-run the clustering pass and check zero-result searches for covered strings before writing more entries.