Subpage Titles on Wikis — Challenges, Conventions, and Compromises

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.)

When a topic has multiple categories, the categories appear in parentheses after the topic name.

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.

Subpages have a slash in the title.

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.

Subpage conventions with WordPress' Codex

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:

Subpages on Mozilla

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.

Subpages on the Embarcadero wiki

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

Subpages on Knoppix

 

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 styleNihiltres{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?

Adobe RobohelpMadcap Flare

This entry was posted in general, wikis on by .

By Tom Johnson

I'm a technical writer working for The 41st Parameter in San Jose, California. I'm primarily interested in topics related to technical writing, such as visual communication (video tutorials, illustrations), findability (organization, information architecture), API documentation (code examples, programming), and web publishing (web platforms, interactivity) -- pretty much everything related to technical writing. If you're trying to keep up to date about the field of technical communication, subscribe to my blog either by RSS or by email. To learn more about me, see my About page. You can also contact me if you have questions.

13 thoughts on “Subpage Titles on Wikis — Challenges, Conventions, and Compromises

  1. CaptNink

    I’ve been struggling with this issue for years. I’m looking forward to reading the comments!

  2. mick davidson

    Tom,
    Excuse my ignorance, but I don’t see the problem. :) However, I can see how it can be a problem if people insist on not using subpages.

    I think it does depend on the ethos being used in the wiki as well. In ours, we use subpages all the time and for a variety of reasons. For a start we don’t want long pages, so if a page can be split (and it’s not being pedantic to do so) we split it. This is because we recognise that there is a hierarchy. We also split pages to remove tables is they’re more than a few rows deep. Most of our tables are lists of fields and their descriptions, which aren’t needed when the user only wants to know how to do something.

    It also helps that in Confluence you can see the tree view, so you can see where you are. But then I have to point out that you got yourself to a page, so you should know where you are. :)

    The examples you show in Wikipedia (one of my favourite places) and WordPress are hideous abominations, a waste of space and very confusing to look at. The information you want it hidden and lost among a thicket of other words, slashes and parentheses – it gives me a headache just looking at it.

    I also agree that working the name into the title isn’t good either (your ACME example).

    Am I wrong in saying that this sort of thing has come about because people refuse to have subpages? Because if it is, then the problem is of their own making. I accept that in reality our wiki doesn’t really have a hierarchy, but it does have a visual representation of one. And because of that I can group pages under one page which is the main page, off of which all the other pages hang. Which means readers can see what goes with what. This approach seems to do away with this problem altogether.

    So am I missing something here, or are people making it harder by trying to force us to work in a way that is actually counter-productive?
    Cheers.

    1. Tom Johnson

      How do you create subpages in Confluence? I’m assuming that if you establish a parent and child page, that relationship is depicted through a tree view hierarchy in the table of contents (TOC). However, if you move outside of that TOC hierarchy, do all files become flat? If so, how do users know what product each topic belongs to?

      1. mick davidson

        Tom,
        yes, that’s exactly how we do it. For example:

        Main Page
        1st Subpage
        2nd Subpage
        3rd Subpage
        1st Subpage
        2nd Subpage
        4th Subpage

        (I hope that renders ok…)

        So far we’ve not had to move outside the TOC hierarchy, so that’s not an issue. Perhaps that a bridge to cross in the future.
        Cheers.

  3. Tim Penner

    Tom,

    I’ve not actually tried this to segregate product documentation in a single wiki, but I would think that a combination of namespaces, cagy categories and sub-categories, and some features of the semantic mediawiki (SMW) extension should be able to produce the effect you’re looking for. I’ve used reporting capabilities that couple with SMW to produce tables of contents, plus you could get inventive with establishing a sort of semantic network around topics. Namespace segregation allows users to search within products. The categories/sub-categories trick (with category tree) allows you to tag articles for their contribution to the subject matter, such as procedures, concepts, etc. One thing’s for certain: if you’ve not played around in SMW then there’s whole new land of possibilities you should very definitely explore if you’re serious about using Mediawiki for heavy multi-product doc work.

    You’ve piqued my curiosity about this. Not that I have the scope to do much about it in the products that I work on, but it wouldn’t take all that much work to zap together an example wiki if you’ve got a some existing documentation to copy.

  4. Mark Baker

    Tom,

    I don’t share you concern about slashes or parentheses. Both are used for many different things, and the intended meaning is clear enough from the examples you provide. On the other hand, it is not the approach I would take.

    Naturally I reject the sub-pages model. Every page is page one, not the sub page of anything else. (How is the person who lands on a sub page from a search supposed to know where they are? And why should they have to go crawling around your hierarchy to figure it out? Not everyone comes in through the TOC.)

    Rather than either of these alternatives, I would challenge the notion that the whole job of establishing context belongs to the title. Title conventions come from the book world, where they function in an established linear context. They are not designed to establish the full context of the the text they head.

    Rather than burdening the title with this additional task, I think we need another mechanism for establishing context in an Every Page is Page One page. In SPFE projects, I have implemented a context header for each page which contains all the pertinent context information: product, version, keywords, topic type, etc. Where appropriate, it also provides links that allow the user to change context if they are in the wrong place.

    I would think a wiki ought to be able support something similar through a page template and variables.

    1. Tom Johnson

      Mark, sorry for my slow reply. I mostly agree with your reasoning here, esp. when you say

      Rather than burdening the title with this additional task, I think we need another mechanism for establishing context in an Every Page is Page One page. In SPFE projects, I have implemented a context header for each page which contains all the pertinent context information: product, version, keywords, topic type, etc. Where appropriate, it also provides links that allow the user to change context if they are in the wrong place.

      I am working on a mechanism to add this context. Right now, usually pages that are part of collections have the context of a sidebar. However, it’s still problematic. When you have generically titled pages, the whole title-style model breaks down.

  5. Gurpreet Singh

    Interesting article.

    I completely agree that things which are obvious in one wiki may be completely difficult in another flavor of wiki. I have used Confluence wiki to manage documentation for a fleet of commercial EDA software having hundreds of User Guides wiht over 500k pages of content and generated chm, pdf and webhelp though a network of perl scripts, pluging and wiki tweaks. It was certainly not easy!

    Copying a new wiki site (which we used to do in every release) was pretty easy though. Just one click and you’d be done. I was amazed to see that how much effort are required to do the same in an opensource wiki like Mediawiki.

    As far as I remember, using tags was the easiest way to group title pages for a productline.

    Just my 2 cents.

    - Gurpreet (http://technicalwritingtoolbox.com)

    1. Tom Johnson

      Gurpreet, would you be interested in writing a guest post that compares Confluence with Mediawiki? It seems like you have experience using both.

  6. Gurpreet Singh

    Hi Tom,

    I’d love to write a blog post for your blog.

    I have tried contacting you on your email (mentioned in your contact page) about writing a blog post few weeks back but didn’t received a reply.

    1. Tom Johnson

      Sorry Gurpreet. I was buried in email a while back. I probably missed the email or flagged it in an action list that I never got to. I’ll try to follow up. Sorry about that.

  7. Pingback: Stuck in a system | I'd Rather Be Writing

  8. Download manuals

    I don’t comment very much, but that doesn’t mean that I don’t follow your posts. I just had to stop by to say that I like to read your opinion and I would like to make you try a little bit more to do your best. There are not lots of sites with high quality on the internet, and this one might be one of the best ones, with a little effort. Greetings from Central Europe!

Comments are closed.