Subpage Titles on Wikis -- Challenges, Conventions, and Compromises

by Tom Johnson on Mar 22, 2012
categories: technical-writing • wikis

One of the challenges with wikis (or at least with Mediawiki) is figuring out how to title pages that all belong to the same product or group. I spent a bit of time researching best practices with this and didn't come up with a clear answer. I tried to also figure out why I'd never come across this page titling conundrum before.

Here's the problem. On a large wiki, you have pages about many different products. For simplicity sake, let's say that on your wiki, you have documentation about products A, B, C, D, and E. Instruction for each of these products is rather long, so rather than having each wiki page contain all the information for the product, you decide to break up the information into smaller pages. After all, you are conscious of people saying TLDR ("too long, didn't read") and simply dismissing your content. So let's say you break up each product's instructional content into 10 pages each.

For product A, some of these topics include titles like Setting preferences, Running reports, Creating widgets, and Adding new users. For product B, you have similar but slightly different topics: Configuring your profile, Exporting reports, Adding widgets, and Setting up new users. The other products have similar topics.

If each product's topics were kept in separate, clearly distinct containers, you wouldn't have much of an issue. And in fact traditional webhelp files do usually segment product information like this. In a traditional help authoring scenario, each product would have its own generated webhelp output, and it wouldn't matter if the topic names were similar because the content would be siloed from each other anyway.

However, wikis are different beasts. Usually an organization's wiki acts as one platform for many products. Help material for products A, B, C, D, and E are all on the same wiki platform. As such, there's a need to distinguish product help from each other through unique page titles.

Wikipedia has several techniques for doing this. At the category level, one technique is to name each category with your base category name, and then add the subcategories in parentheses after the base name. You have to see this in action to really grasp it. Check out their Manual of Style. This Manual of Style is rather large. If editors put it all on one page, you could probably scroll down for hours before you reached the end. So they divide this content into various categories. Categories are like chapters. There's a category about formatting, images, layout, and more. (See all categories.)

Rather than just listing category titles as "Formatting," they write "Manual of Style (formatting)." In other words, they include the product name first, and then put the category name in parentheses following the product name. Presumably this is because readers need to know that the category fits within the Manual of Style and is not just about formatting in general.

When you click the Formatting category, Wikipedia implements another technique: the slash. The Manual of Style (formatting) category has pages in it with names like "Manual of Style/Dates and numbers," "Manual of Style/Capital letters," "Manual of Style/Proper names." "Manual of Style" is the base page name, and the title after the slash is a subpage for that page.

If this weren't enough, Wikipedia also incorporates a namespace for this specific category. The actual title of these pages is "Wikipedia:Manual of Style/Proper names." The namespace puts the page into a specific space that segments the content differently in searches. Content in the Wikipedia namespace discusses the Wikipedia wiki itself.

The slash is a fairly common convention on wikis for denoting subpages. WordPress's wiki uses slashes in titles for their Function Reference subpages.

Interestingly, this appears to be one of the few examples of subpages on the WordPress Codex wiki. Their style guide cautions against subpages as follows:

Do not create sub-pages of a page, other than from your own User page, without discussing first on the wp-docs mailing list. Exceptions to this are the pages under Function Reference (each of which describes a single function).

Undoubtedly, neither the parentheses nor the slash provide elegant ways of titling pages. Imagine titling every one of your help pages with the product name first, followed by a slash with the real page name. At the same time, imagine not including the base page in the page's title. The function references shown above would be a mess!

The subpage name technique is ugly for at least two reasons. First, it's ungrammatical. Traditionally, the slash denotes an either/or significance, so writing Manual of Style/Proper Names literally means that you could refer to the content either as a Manual of Style or Proper names; the two words are both interchangeable or applicable. This is not really the case, though.

Parentheses aren't much better. "Manual of Style (Proper names)" suggests that Proper names might be an alternative name for Manual of Style. Parentheses traditionally indicate a whisper or an aside comment.

Only those familiar with Wikipedia's conventions, or who guess the meaning of the conventions based on the context of the titles they're seeing, will understand the real meaning of the slash or parentheses.

Despite the unconventionality of titling pages this way, slashes seems to be the convention on wikis for denoting subpages. Here's how Mozilla's wiki uses subpages:

Not all wikis use subpages. The Embarcadero wiki doesn't seem to use them. If they need subpages, they put the subpage name in parentheses.

The Knoppix wiki just seems to use subpages for things like bugs.

 

Other options for article titles are also problematic. Some people recommend that you start the page name with the product title. With this method, you end up with titles such as Acme Configuring your profile, Acme Exporting reports, Acme Adding widgets, and so on (assuming your product's name is "Acme"). Sometimes this works. Many times it doesn't.

An alternative might be to integrate the product title somewhere in the article title. For example, Configuring your Acme profile, Exporting reports from Acme, Adding widgets to Acme, etc. This is all right, but what happens when the product name doesn't fit into the title? What if the product name is long and unwieldy, or a clunky acronym? What if your product name is Linguistic Analysis Algorithm Identifier, or something horrendous?

Another approach is to leave out the product name from the title altogether. If you have a sidebar with the collection name, that sidebar will provide some context about the product. This allows you to use graceful looking titles, but this method falls short when the sidebar isn't included with the appearance of the page title. Search results, category lists, recent updates, page lists, and other areas of the wiki will not include the contextual sidebar.

I'm somewhat baffled by this page titling conundrum. I'm leaning towards the slash method only for content that has a clear top page, as pointed out in this heated discussion thread. In general, I would like to omit subpages in titles altogether. In this same thread, one person notes that subpages are usually unnecessary because articles should stand by themselves:

Aside from arguments based on technical or usability details (subpages do not have breadcrumbs in the main article space, newbies would find them confusing), we don't use subpages in the main namespace because they should instead be valid articles in and of themselves. This is the practice; for example History of Canada is effectively a subpage of Canada, but is valid as an article in its own right. Indeed, it's a guideline that Good and Featured articles must follow to some extent: Wikipedia:Summary style. Nihiltres^{t.l} 19:01, 20 April 2008 (UTC) (See thread.)

This is perhaps why articles on Wikipedia are so long. What do you recommend in this situation?