One Page, One Topic: Why I Introduced Content Granularity into a Learning Site
Introduction
In the early days of building this site, I was writing articles that combined multiple topics — “What is Astro,” “How to install Astro,” and “How to create your first page” — into a single document. My reasoning was that combining information in one place would be more convenient. But as the number of articles grew, a problem emerged: readers had difficulty knowing which article covered what. This experience led me to introduce the “one page, one topic” design policy.
What the One Page, One Topic Policy Means
The one page, one topic policy means that a single article explains only one thing.
“What is Astro” and “How to install Astro” become separate articles. If a reader wants to understand the concept of Astro, they read that article. If they want to know how to install it, they read that one. The principle is to keep article units small so that readers can go directly to the article that matches their goal.
Why I Introduced This Policy
Readers Could Not Reach the Information They Needed Directly
In articles that combined multiple topics, readers had to scroll through the entire article to find the information they were looking for. For a reader who only wanted to know how to install something, the overview section at the top of the article was content they did not need to read.
With the one page, one topic policy, readers can select the relevant article from the sidebar or a link, and the entire article addresses their specific goal.
Search Engines Have an Easier Time Determining the Subject of an Article
When multiple topics coexist in a single article, it becomes harder for search engines to determine the main subject. An article mixing “What is Astro” with “Installation instructions” ends up partially addressing both search intents without fully addressing either.
Keeping each article to one topic allows search engines to accurately identify what the article is about.
Articles Are Easier to Update and Manage
When Astro’s installation procedure changed, updating an article that contained multiple topics meant reviewing the entire article, including sections unrelated to the change — the overview, for example. When topics are separated into individual articles, only the article that needs updating has to be reviewed, making the scope of revisions clear.
How I Decide What Counts as “One Topic”
There are boundaries where it is easy to hesitate about whether to split. Here are the criteria I actually use.
“Why do it” and “how to do it” are separate topics
“Why I chose Astro” and “How to set up Astro” serve different purposes. The first is for readers who want to understand the reasoning behind a choice. The second is for readers who want to take action. When readers’ goals differ, I make them separate articles.
“Explanation of a concept” and “steps for an operation” are separate topics
“What is frontmatter” (concept) and “the fields to include in frontmatter” (reference information) can be combined in one page, but when an article becomes long, they become candidates for splitting. “Understanding a concept” and “carrying out an operation” are distinct goals for a reader.
“When in doubt, split” as a principle
When I am uncertain, I choose to split. Related content can still be connected afterward by adding internal links between articles. Once content is combined into one article, it becomes harder to split it later.
How Things Changed in Practice
After introducing this policy, the number of articles in the sidebar increased, but the word count per article decreased. I have the sense that it became easier for readers to reach the article that matched what they were looking for.
In terms of managing articles, it became easier to identify which topic needed updating. When a command changed due to a version upgrade, the articles that needed updating — “Installation procedure” and “Upgrade procedure” — became clearly identifiable.
Summary
The one page, one topic policy means a single article explains only one thing. I consider this approach effective from three perspectives: reader convenience, search engine compatibility, and the efficiency of article management. Keeping the principle “when in doubt, split” in mind speeds up the decision-making process.