docs: cut the subtitle from the guide article titles - #469
Merged
Conversation
The 23-part guide series titles each carry a subtitle after a `--`, which puts them between 80 and 190 characters. A search result shows nothing like that much, so what a searcher sees is the series number and the first few words of the topic, cut mid-phrase. Measured in Search Console over the last three months, the article pages draw 17,900 impressions -- 9.6% of the site -- at an average position of 9.6, which is the same as the site as a whole, but convert at 1.5% CTR against the site's 3.3%. Ranking is not the problem; the result listing is. The subtitle is dropped from the heading and the rules are resized to the new title's display width. The series number is kept, so the parts still read as a series. Nothing is reworded. Scope is `guide-*.rst`. `article-*.rst` is deliberately excluded: there the text after the separator is what tells the four articles apart (installation, API, FSS), so removing it would leave each language with four pages under one title. The information is not lost. Each guide opens with an Introduction that already states what the subtitle said. Result, measured by display width rather than character count -- Google truncates on width, and a character count understates CJK by half: article titles wider than 60 columns fall from 177 to 52. Of the 52, 31 are guides whose main title alone is long, all of them in German, English, Spanish or French; 21 are the excluded article series. Every Japanese, Korean and Chinese guide title now fits. No new duplicate title is created, and `tools/check_headings.py` is clean across every article directory.
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
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 23-part guide series carries a subtitle after a
--in every title, which puts them between 80 and 190 characters. A search result shows nothing like that much, so what a searcher actually sees is the series number and the first few words of the topic, cut mid-phrase.Why these pages
Measured in Search Console over the last three months:
The articles rank where the rest of the site ranks and convert at less than half the rate. Ranking is not the problem; the result listing is. For scale, this is ten times the impressions of the description-less hub pages fixed in #468.
What changed
The subtitle is dropped from the heading and the over/underline rules are resized to the new title's display width. The series number stays, so the parts still read as a series. Nothing is reworded.
Scope is
guide-*.rst— 161 files, 23 guides across 7 languages.article-*.rstis deliberately excluded. There the text after the separator is what tells the four articles apart (installation, API, FSS), so removing it would leave each language with four pages under a single title.en/articles/article-4.rstuses the same--separator and is excluded for this reason.The information is not lost: each guide opens with an Introduction that already states what the subtitle said.
Result
Measured by display width, not character count — Google truncates on width, and a character count understates CJK by about half, so a 35-character Japanese title takes the room of a 70-character English one while a character count still calls it short.
Of the 52 that remain:
Every Japanese, Korean and Chinese guide title now fits.
The 31 guides still over 60 columns
By language: French 12, Spanish 10, German 5, English 4. The widest are
fr/articles/guide-22(108),es/articles/guide-22(95) andfr/articles/guide-23(95). In each case the topic itself is long in that language; shortening it means rewording, not cutting.Verification
tools/check_headings.pyis clean across every article directory, not only the current versions.Found while doing this, not fixed here
31 Japanese and Chinese article pages render a visible space between two CJK characters in their body text. The source writes one sentence per line inside a paragraph, and docutils turns that line break into a space. It is pre-existing — this branch touches only heading lines — and it affects 569 line pairs across 55 files. The generated
meta descriptionis unaffected because the generator strips those spaces, so this is a readability defect rather than a search one, and it is large enough to deserve its own change.