Skip to content

docs: use fictitious data and make the phone reference reachable - #67

Merged
trichardswp merged 2 commits into
mainfrom
phone-docs-followup
Oct 2, 2026
Merged

trichardswp merged 2 commits into
mainfrom
phone-docs-followup

Conversation

@lhagenWP

@lhagenWP lhagenWP commented Oct 2, 2026 •

Copy link
Copy Markdown
Collaborator

Why

Two things that shipped in the phone lookup docs need correcting.

The examples were real. They were a response captured from a running
service: an identifiable business, its carrier, its number. They are published
now.

The reference page has no way in. /references/phone-v2/get_phone_by_number_v2
exists and renders, but the References rail lists its directories by hand and
phone-v2 was not among them. A reader reaches the page only by typing the
URL. Getting Started mentions a phone number only as something person search
accepts as a parameter.

What Changed

Examples in the guide and the changelog are fictitious: John Smith on
(206) 555-0142, placeholder identifiers, matching what the other guides use.
Phone numbers come from the 555-01xx range reserved for documentation, and a
callout on the guide says the values are invented so nobody mistakes them for
live data.

The business example stays, because approximate_locations needs a business to
illustrate and that is the endpoint's new capability — but the business is
invented too.

phone-v2 is added to the References rail, after person-v2. Getting Started
gains a Phone Lookup card beside Person Search and a mention in Next Steps.

The reference pages are regenerated from the published spec, as a second
commit. The service stopped publishing its handler docstrings, so the spec no
longer carries numpydoc sections or the reStructuredText markup this site
renders as literal backticks. Descriptions only, on five pages: the phone
lookup loses a Parameters and Returns block naming Python arguments and
internal types; person, property and deed-event search lose Raises blocks
naming exception classes; the property detail page's code spans render as code.

Context

The rail file is hand-maintained; the generator writes each directory's own
meta.json but not the parent list, which is why generating the page did not
make it reachable. Worth knowing for the next endpoint that gets added.

The regeneration had to wait for the service change to reach production, since
the generator reads the live spec at api.whitepages.com/openapi.json. I
confirmed the deployed image is that change's merge commit and that the live
spec has no remaining leaked sections before regenerating.

@lhagenWP
lhagenWP force-pushed the phone-docs-followup branch from 290af0e to 1c86ef2 Compare October 2, 2026 17:54
The phone lookup examples were a live response captured from a running
service: a real business, its real carrier, its real number. Replace
them with fictitious values on the pattern the other guides already
use, from the 555-01xx range reserved for documentation, and say so in
the guide. The business example stays, since approximate_locations
needs one to illustrate, but the business is invented too.

The reference page had no way in. The References rail lists its
directories by hand and phone-v2 was missing from that list, so the
page was reachable only by typing its URL. Getting Started mentioned a
phone number only as something person search accepts.
The service stopped publishing its handler docstrings, so the spec these
pages are generated from no longer carries numpydoc sections or the
reStructuredText markup the site renders as literal backticks.

Descriptions only. Five pages: the phone lookup loses a Parameters and
Returns block naming Python arguments and internal types, person,
property and deed-event search lose Raises blocks naming exception
classes, and the property detail page's code spans render as code.
@lhagenWP
lhagenWP force-pushed the phone-docs-followup branch from 1c86ef2 to b5ace22 Compare October 2, 2026 19:43
@trichardswp
trichardswp merged commit 6da163f into main Oct 2, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants