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

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

This guide gives you a quick introduction to the most important tasks and concepts in WordPress. It divides these tasks and concepts into five sections, outlined below:

Get Set Up

• 1.1 Advantages of Self-Hosted WordPress Blogs
• 1.2 Become Familiar with FTP
• 1.3 Install WordPress on Your Web Host
• 1.4 Explore Your New WordPress Blog
• 1.5 Configure General Settings
• 1.6 Import Your Content from Blogger or Elsewhere

2 Create Content

• 2.1 Write a Post
• 2.2 Create a Page
• 2.3 Make Categories for Your Posts
• 2.4 Add Tags to Your Posts
• 2.5 Edit a Page or Post

3 Style Your Site

• 3.1 Change Your Theme
• 3.2 Modify Your Sidebar
• 3.3 Customize Your Header Image or Background
• 3.4 Configure How Your Pages Appear
• 3.5 Make It Easy to Subscribe to Your RSS Feed

4 Add More Functionality

• 4.1 Install a Plugin
• 4.2 Activate Akismet to Stop Spam
• 4.3 Create a Regular Database Backup
• 4.4 Include a Contact Form
• 4.5 Install Other Needed Plugins

5 Understand the Code More

• 5.1 Understand A Little Bit About Template Tags (PHP)
• 5.2 Modify Your Theme’s Appearance
• 5.3 Understand Your Theme’s Files
• 5.4 Recognize the Loop
• 5.5 Learn How to Upgrade Your Blog Software
• 5.6 Learn How to Get Help

I wrote the guide because I’ve felt, for some time now, that the WordPress Codex is too massive to be useful for anything more than reference information. There needs to be a shorter, more concise way of getting up to speed with WordPress.

I think my basic organization and content is okay, but the wiki format is challenging. It looks quite long, it’s not too printer friendly (although you can print it), and there aren’t any images (which means it’s not very visually attractive). Writing in wiki format is hard (easy to write, hard to make look professional).

If you have any suggestions for how I might improve the Quick Start Guide, let me know. Actually, if you want to get involved as a WordPress Codex author/editor, see Contributing to WordPress. After you register for an account and log in, and then change the skin to Monobook, you’ll see an Edit button you can click to edit the wiki content. I’d love if it some of you out there actually edited this guide.