home: make it obvious what to click on the front page - #2780
Merged
Merged
Conversation
The front page was five headings of bulleted links at the same visual weight, so nothing said what to click first. Put the upcoming conferences at the top where the dates are useful, give Slack, the guide and meetups a card each, and let everything else be a plain list further down. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015JdLb6hXkD9Vym4eABf8pg
Documentation build overview
17 files changed ·
|
Drop the bullets from the conference list so the dates read as a list of events rather than bulleted prose, and let the accent belong to that block alone. The doors are plain boxes now, coloured only on hover. Send people browsing for documentation reading to the topic index rather than the guide: it is sorted by what people want to know about, which is a better first stop. The guide moves to the list below. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015JdLb6hXkD9Vym4eABf8pg
Renaming the front page sections broke the anchor this 2019 post links to. "More from Write the Docs" is what "many other projects" meant anyway. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015JdLb6hXkD9Vym4eABf8pg
It is more newsletter writing than talks, and the range is the draw: over 700 pieces across twelve topics, from craft questions to career ones. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015JdLb6hXkD9Vym4eABf8pg
Slack and the newsletter are the two things most people actually stay for, so they take the first two cards and meetups moves to the list. The topic index page called itself an archive, in no particular order, which reads as dead storage. It is neither: say how much is in it and how it is sorted. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015JdLb6hXkD9Vym4eABf8pg
The local contents ran to full depth: 64 nested entries, 1,773px of bullets before the first piece of content. One level, laid out as a grid, fits on a screen and shows the range of the page at a glance. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015JdLb6hXkD9Vym4eABf8pg
ericholscher
marked this pull request as ready for review
September 22, 2026 15:00
ericholscher
requested review from
a team and
plaindocs
and removed request for
plaindocs
September 22, 2026 15:31
Site Content listed whatever happened to be in the visible toctree: the surveys, the guide, the book club and the about pages. Conferences, Slack, meetups, the newsletter and the topic index were all in the hidden glob that registers every conference page, so none of them ever appeared. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015JdLb6hXkD9Vym4eABf8pg
The front page carried the nav twice: once in the sidebar, once as a Site Content list that repeated it and overlapped the resources list above. Move the sidebar nav to extra_nav_links so the front page toctree only has to register pages, and keep the nav to the places worth reaching from anywhere. Everything else is on the front page and in the site map. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015JdLb6hXkD9Vym4eABf8pg
plaindocs
approved these changes
Sep 22, 2026
plaindocs
left a comment
plaindocs
left a comment
Contributor
There was a problem hiding this comment.
Hell yes to most of this, couple of nits:
- the green in upcoming conferences looks like conference green, which confuses me (but 99.9% of people won't care)
- this entirely demotes the salary survey, maybe a 4th card?
- do we want (x videos, y write ups) in the topic cards?
Cutting the jobs section took the participation link with it, leaving only the results. The 2026 survey is open now, and the front page was the one place outside the blog that asked people to contribute. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015JdLb6hXkD9Vym4eABf8pg
Meetups, the salary survey and sponsorship were plain list items among ten others, which put them below the fold and at the same weight as the book club. Give them cards, and drop their duplicate lines from the list. The salary survey card links to the results page and to the open 2026 survey, so the front page still asks people to contribute. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015JdLb6hXkD9Vym4eABf8pg
Member
Author
We're actually using the green in buttons already as an accent, so the AI ran with it. Seems fine for now 🤷 Fixed the salary survey by moving it to a top-level button. I think the topic cards could be improved, but baby steps :) |
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
3 participants
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.
The front page was five headings of bulleted links at the same visual weight, so nothing told a first-time visitor what to click. The conference dates — the most perishable thing we publish — sat in the same plain list as the topic index.
Now: upcoming conferences at the top, three cards for Slack, the newsletter and the topic index, and everything else in a plain two-column list. "Find or advertise a job" is gone as a heading; two of its three links were about the salary survey anyway.
The third card is the topic index rather than the guide, because it's sorted by what a piece is about — you arrive with a problem and leave with what the community has said about it. That meant cleaning up the page itself: it called itself an archive when it's 705 live entries, and its local TOC ran to 64 nested items before the first link. It's now a grid of the twelve topics.
See it
Worth a look
/#connect-with-the-community, which a 2019 blog post linked to. It now points at#more-from-write-the-docs. Inbound links from outside will break.sidebar_includehidden: False.Generated by Claude Code
📚 Documentation preview 📚: https://writethedocs-www--2780.org.readthedocs.build/