docs: fix stale content, dead links, and missing nav entries - #450
Draft
netravnen wants to merge 9 commits into
Draft
docs: fix stale content, dead links, and missing nav entries#450netravnen wants to merge 9 commits into
netravnen wants to merge 9 commits into
Conversation
A codebase-onboarding pass flagged two minor doc issues: README.md's
CentOS setup step predates this repo's move to a venv + uv workflow,
and mkdocs.yml's commented-out repo_url ("Edit on GitHub" link) had
only a generic comment with no indication of whether it was disabled
on purpose. Confirmed via git history that the link was deliberately
removed (commit fcb252c, "Removed the 'Edit on GitHub' link.",
2024-02-05), though that commit itself records no reason -- so this
leaves it disabled and documents that provenance instead of guessing
at intent either way.
Changes:
- README.md: CentOS install step used `yum install python-pip`,
the Python 2 package name on a package manager CentOS has since
moved on from; updated to `dnf install python3 python3-pip` to
match the rest of the guide's python3/venv-based setup
- mkdocs.yml: replace the one-line "This line adds the Edit on
GitHub link" comment above the commented-out repo_url with one
that records why it's off (deliberate removal, reason
undocumented) so it reads as a known state, not leftover cruft
Security:
- N/A -- documentation only
Testing:
- N/A -- text-only changes; no build step to run for README.md, and
mkdocs.yml's only functional line (repo_url) is unchanged, still
commented out
Backwards Compatibility:
- N/A -- no behavior change; the Edit on GitHub link remains off,
matching current site behavior
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…ber steps
The getting-started path was scattered: index.md buried the
role-specific HOWTOs under 45 lines of archival material (release
notes, tools, presentations, beta server, historical data), the four
get-started-*.md guides each repeated an identical 370+ word "About
PeeringDB" paragraph, and their setup steps were an unordered list
that read more like notes than instructions. This restructures the
front door so a new user hits a role picker first and each guide
gets straight to numbered steps.
Changes:
- docs/index.md: move "Getting started" to the second section (after
the intro video, before Policies); consolidate Release
notes/Tools/Presentations/Open source/Beta/Historical data into a
compact "Learn more" bullet list; move the tutorial/workshop list
out to presentations.md; trimmed from 123 to 92 lines
- docs/howtos.md: add a "New here? Start with your role" intro
linking the four get-started guides, and list query_the_api.md
alongside search.md
- docs/howto/get-started-{operator,exchange,facility,carrier}.md:
replace the duplicated "About PeeringDB" boilerplate with a single
pointer to index.md; number the setup steps (create account,
create org, create the role-specific object, follow-up step);
standardize the "Why should I add my network?" heading to "Why?"
to match the other three guides; add the missing "More
information" section to get-started-carrier.md so all four guides
match
- docs/presentations.md: add "Tutorials and workshops" section at
top with the 7 entries moved from index.md
Security:
- N/A -- documentation only
Testing:
- mkdocs build --strict passes with 0 warnings; internal links
between index.md, howtos.md, and the four get-started guides
verified to resolve
Backwards Compatibility:
- N/A -- no URLs or anchors removed; index.md's #mailing-lists
anchor (linked from 60+ blog posts) is unchanged
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
search.md had grown to 355 lines serving two audiences at once: a
beginner walkthrough of UI/browser-extension search, and a full API
reference (object types, authentication, curl/Python/jq examples).
Separately, authenticate.md's MFA section was four sentences with
three screenshots sitting unused in the images directory, leaving
users to figure out setup and org-level enforcement on their own.
Changes:
- docs/howto/query_the_api.md: new file (175 lines) with the API
reference content moved from search.md -- object types
(basic/derived), API key authentication, making requests, GET
operations on single/multiple objects, nested sets/objects, and
real-world query examples using curl, Python, and jq
- docs/howto/search.md: trimmed from 355 to 189 lines, now focused
on UI/extension search; replaced the removed content with a
pointer to query_the_api.md
- docs/howto/authenticate.md: expanded the MFA section into a full
walkthrough with two new subsections ("Setting up your second
factor", "Requiring MFA for your organization"), wiring in the
three previously orphaned screenshots
(Location_of_MFA_button.png, MFA_management.png,
require_users_to_enable_2fa.png) with captions
- docs/howto/work_within_peeringdbs_query_limits.md,
docs/release_notes/release_notes_2023.md: update cross-references
from /howto/search to /howto/query_the_api/ to match the split
Security:
- N/A -- documentation only
Testing:
- mkdocs build --strict passes with 0 warnings; verified
query_the_api.md anchors referenced by other pages resolve
Backwards Compatibility:
- search.md's URL is unchanged; only its content and length
changed, so existing external links to /howto/search/ still
resolve, just to a narrower page
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
A link sweep across the docs site found three broken references unrelated to the getting-started or API-split work: an FAQ anchor pointing at a section that no longer exists, and two blog posts linking to HOWTO pages that were renamed or never existed. Changes: - docs/faq.md: "How do I get started?" linked to http://docs.peeringdb.com/#quick-start, an anchor that doesn't exist in index.md; replaced with a link to /howtos/ describing the role-based guides - docs/blog/mfa_mandatory.md: "second factor" linked to /howto/enable_require_2fa/, a page that was never published; redirected to /howto/authenticate/#multi-factor-authentication-mfa - docs/blog/peeringdb_2022_user_survey.md: "HOWTO documentation series" linked to /howto/ (404, missing the plural); fixed to /howtos/ Security: - N/A -- documentation only Testing: - mkdocs build --strict passes with 0 warnings; confirmed /howto/authenticate/#multi-factor-authentication-mfa resolves in the generated HTML Backwards Compatibility: - N/A -- these links were already broken; no working URLs changed Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The Admin Committee's public-facing Deskpro response snippets (triggered via ;code shortcuts like ;net-approved) had no human-readable index, making them hard to review or reference outside the Deskpro UI itself. Changes: - docs/committee/admin/deskpro_snippets.md: new file indexing the public (non-staff-only, non-trivial) Deskpro snippets by category -- network registration & approvals, facility & carrier management, organization recovery & account verification, IP/IX-F conflict resolution, and general administrative responses -- with snippet ID, shortcut code, and full text for each Security: - N/A -- documentation only; content already public-facing via Deskpro shortcuts, this just mirrors it Testing: - mkdocs build --strict passes with 0 warnings Backwards Compatibility: - N/A -- new page, no existing links affected Co-Authored-By: Gemini 3.6 Flash <noreply@google.com>
…uidance Facility, exchange, and carrier applicants were finding out they didn't qualify only after submitting and getting rejected, because the eligibility bar for each object type lived only in the Admin Committee's Deskpro response snippets, not in the public HOWTOs. Likewise, none of the three guides warned that facility and IX prefix objects can't be deleted once other records depend on them, so operators hit that block with no context. Changes: - docs/howto/get-started-facility.md: add "Facility qualification & approval criteria" section (ownership/operation, public colocation, multi-carrier interconnection, public documentation, and explicitly ineligible site types) and a "Deleting a facility" warning admonition covering the connected-networks deletion lock - docs/howto/get-started-exchange.md: add a "3-ASN minimum" callout covering the participant threshold, route-server/affiliated-ASN exclusions, and RDAP-verifiable prefix requirements, plus a "Deleting an IX prefix" warning admonition covering the connected-networks deletion lock - docs/howto/get-started-carrier.md: add "Carrier infrastructure qualification checklist" distinguishing eligible carrier-grade services (dark fibre, DWDM/wavelengths, Ethernet transport, MPLS VPN over owned infrastructure) from ineligible resold/leased transport Content is sourced from the Admin Committee's public Deskpro snippets already indexed in committee/admin/deskpro_snippets.md (;fac-rejected, ;ix-rejected, ;car-rejected, ;deletion-fac, ;deletion-ixpfx) -- this makes criteria the committee already applies visible to applicants before they submit. Security: - N/A -- documentation only Testing: - mkdocs build --strict passes with 0 warnings; admonition blocks confirmed to render as `class="admonition warning"` / `class="admonition important"` in the generated HTML Backwards Compatibility: - N/A -- additive content only, no headings renamed or removed, no existing anchors changed Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Plan-By: Gemini 3.6 Flash <noreply@google.com>
…locks Two recurring support patterns had no self-serve documentation: users whose account email didn't match their ASN's RDAP record had no way to learn that adding a secondary email would unblock automated affiliation approval, and users who inherited an ASN or lost contact with their org's admins had no documented path to reclaim access. Separately, faq.md's Technical section covered API and sync mechanics but nothing about why object deletion sometimes gets blocked. Changes: - docs/howto/authenticate.md: add "Organization affiliation & admin succession" section with two subsections -- "RDAP email verification" (how the RDAP match works, why adding a secondary email is faster than changing your login email) and "Claiming admin rights for an existing organization" (contacting a reachable admin first, falling back to RDAP-verifiable proof via support, and what to provide after an ASN acquisition) - docs/faq.md: add "Why can't I delete my Facility, IX Prefix, or Point of Contact?" under Technical, covering all three deletion locks and how to resolve each Content is sourced from the Admin Committee's public Deskpro snippets already indexed in committee/admin/deskpro_snippets.md (;mismatch-email, ;contacts-existing-admins, ;deletion-fac, ;deletion-ixpfx, ;deletion-poc). Security: - N/A -- documentation only; no new authentication mechanism described, just an explanation of an existing one Testing: - mkdocs build --strict passes with 0 warnings; new mailto and RDAP links verified to resolve Backwards Compatibility: - N/A -- additive content only, no headings renamed or removed Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Plan-By: Gemini 3.6 Flash <noreply@google.com>
committee/admin/deskpro_snippets.md and howto/query_the_api.md were only reachable via inline links from their parent pages -- mkdocs build listed both as present but not included in nav. Neither is a broken build (mkdocs only warns at INFO level for this), but it meant visitors browsing the site nav tree had no way to discover either page. Changes: - mkdocs.yml: nest "Admin Committee" into "Overview" (index.md) and "Deskpro Snippets" (deskpro_snippets.md); nest "HOWTOs" into "Overview" (howtos.md) and "Query the API" (query_the_api.md) Security: - N/A -- documentation only Testing: - mkdocs build --strict passes with 0 warnings; both pages no longer appear in the "not included in nav" info listing Backwards Compatibility: - N/A -- existing page URLs are unchanged; this only adds entries to the nav tree Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Plan-By: Gemini 3.6 Flash <noreply@google.com>
The FAQ had no guidance for a recurring support scenario: a company acquires another company and wants to bring the acquired organization's PeeringDB resources under its own management. Users hitting this had to file a support ticket cold, with no documented process or expectations set in advance. This also complements the "Organization affiliation & admin succession" section already added to authenticate.md, which covers the adjacent but distinct case of claiming admin rights when the original admins can't be reached. Changes: - docs/faq.md: add "Mergers and Acquisitions" under General, right after "Affiliation requests" -- covers the acquisition scenario, a worked example (Company A acquired by Company B), the support ticket process, and what speeds up review (writing from an email address that admins both organizations); cross-references authenticate.md's admin-succession guidance for the unreachable-admin case - docs/howto/authenticate.md: add a reverse cross-reference from "Claiming admin rights for an existing organization" to the new FAQ entry, for the voluntary-handoff case where the acquired organization's admins are still reachable Security: - N/A -- documentation only Testing: - mkdocs build --strict passes with 0 warnings; both cross-reference anchors (#mergers-and-acquisitions, #claiming-admin-rights-for-an-existing-organization) confirmed present in the generated HTML Backwards Compatibility: - N/A -- new content only, no existing links or anchors changed Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This was referenced Aug 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Split out of #449 to make review easier. The infra half (fork-preview
banner, dual Atom feeds, gh-pages reset) moved to #451; #448
is the tracking issue for the whole line of work.
This is a batch of independent content fixes that accumulated while
working on the fork-preview infra in #449. None of it depends on that
infra work, so it can be reviewed and merged entirely on its own.
Changes
stays disabled.
numbered steps.
howto/search.md: split the API reference out into its own page,expanded the MFA guide.
qualification criteria, Mergers & Acquisitions guidance.
sidebar.
Testing
uv run mkdocs build --strict-- 0 warnings.