Wikibooks:Hierarchy naming scheme

Books on Wikibooks should be structured in to sections (akin to chapters), in a manner at the discretion of the authors of the Wikibook. However, there is no one method of denoting substructure within Wikibook article names. This page is to discuss the merits of the currently used methods and to decide on a method to use, which will then become a definite recommendation to future books on Wikibooks:Naming conventions.

There are several issues involved in the naming convention, and it is the cleanest to discuss them separately (for example, which delimiter (":", "/", "(..)",..) to use is more or less independent of the question whether to allow several levels of hierarchy or whether numbers should be used for labelling chapters). Each section states current examples.

Please add to advantages or disadvantages below, or provide discussion alternatives.

Delimiters

Subpages "/"

One method is to use subpages, that is, for a Wikibook named bookname, and a subpage called subpagename, the article name is bookname/subpagename.

Wikijunior Solar System
Wikijunior Solar System/Mars
Wikijunior Solar System/Glossary

Advantages:

• The main merit to this scheme is that it allows for automatic navigation links within the hierarchy.
• This allows hierarchy but also allows sub-subhierarchy and more.
• Every sub(sub..)page gets a static link to all its parents. One can reference to subpages with [[/subpagename]] (i.e. bookname is not necessary).
• It will appear similar to directories in the URL as pointed out 1 1/2 years ago [1] and in that sense also follows in principle the principle of least surprise.

Disadvantages:

• The main demerit is that the scheme facilitates the use of subhierarchies, which may make the book slightly more difficult to read or present. Also, authors might be tempted to over-use the tree-structure. It might therefore be part of the recommendation, to use only one level of subpages, and a second only if needed in very large books (see separate discussion point below).
• Links from one subpage to another subpage must be typed in full. Further, the pipe trick does not work for subpages; [[Bookname/Subpagename|]] displays as Bookname/Subpagename
• All links to subpages are case sensitive; Wikijunior Solar System/The Sun vs Wikijunior Solar System/the Sun
• The delimiter "/" will interfere with the filesystem when one wants to save files and automatically process them by scripts and simple UNIX commands like grep. It would be required to use additional commands like "mkdir", "find", and "xargs".
• The enforced tree structure is unsuitable for many uses. For example: anise is a spice, herb, and vegetable. There is no correct way to set this up such that automatic links will be provided for all uses of anise. One would have to choose more general tree nodes, like "glossary/anise" or a completely flat structure ("cookbook/anise").

Real custom namespaces

One method is to use custom namespaces, that is, for a Wikibook named bookname, and a subpage called subpagename, the article name is bookname:subpagename. Examples:

• Cookbook
• Cookbook:Grilled Cheese Sandwich
• Cookbook:Contributors

Advantages:

• This scheme is like other namespaces, and as such, follows the principle of least surprise.
• Linking becomes simple using the pipe trick; [[Bookname:subpagename|]] becomes subpagename.
• Special:Allpages can be applied to a book of choice.
• User contributions can show all, or be restricted to a book of choice.
• From MediaWiki 1.5 Recent changes ditto; for this, Allpages and User contributions, one can also select all namespaces except a specified one; thus, one can still have a combined list including all book pages by selecting e.g. the image namespace and using the invert option.
• Searching can be restricted to any subset of books.
• The variables {{NAMESPACE}} and {{PAGENAME}} give the book name and the page name without book name, respectively.

Disadvantages:

• Creation, deletion, and renaming of a custom namespace can only be done by a developer (when a new book is started, provisionally a pseudo-namespace can be used, see the next section).
• The maximum number of "real" namespaces is limited by the software to 256 (it is a TINYINT(2) in the SQL database), i.e. numbers 0-255. Custom namespace numbers start with 100, so there can be 156 of them, including talk pages, i.e. 78 custom namespaces and their talk namespaces. However, from MediaWiki 1.5 the maximum is 65,536, i.e. 32,718 custom namespaces and their talk namespaces, see Bugzilla:719.

Pseudo-namespaces

Another method is to mirror that of namespaces, that is, for a Wikibook named bookname, and a subpage called subpagename, the article name is bookname:subpagename, like above.

Advantages:

• The main merit to this scheme is that it is mirrored in namespaces, and as such, follows the principle of least surprise.

Disadvantages:

• The main demerit is that this scheme doesn't act as a namespace, but merely looks like one .
• With pseudo-namespaces, the pipe trick still works, but the first letter of the subpage name is case sensitive, which makes them less useful for inline links.

Brackets "(..)"

One method is to use brackets, that is, for a Wikibook named bookname, and a subpage called subpagename, the article name is subpagename (bookname).

General Biology
Energy and Metabolism (General Biology)
Authors (General Biology)

Advantages:

• Similar to Wikipedia's disambiguation, people coming from Wikipedia will be familiar with this.
• This allows for easier linking, using the pipe trick; [[subpagename (bookname)|]] appears as subpagename.

Disadvantages:

• More difficult to extract a list of books automatically in the future (see Wikibooks:Top active/All books). In an automatic extraction it is more difficult to tell apart a book title from the middle of a string, because it might be part of another subpage title. The extraction process is unique, if the bookname always appears on the front position.

No delimiter, no book title on subpages, all in wikibooks.org domain

One method is to use no delimiter at all, that is, for a Wikibook named bookname, and a subpage called subpagename, the article name is subpagename (i.e. the bookname does not appear).

World History
Civilization and Empires in the Indian Subcontinent  (<- this is a subpage of World History!)
The Industrial Revolution    (<- this is a subpage of World History!)

(World History pages have been changed in the meantime to namespace delimiter. The lines are kept as an example)

Vector Math (<- this single modules is referred to in the middle of the Geometry, Calculus, and Electronics books)
ASCII character set (<- this single module is referred to in the appendix of just about every programming language)

Advantages:

• Title of subpages does not get cluttered by long book title.
• Normal wiki ease-of-use is fully restored: [[foo]] instead of [[Bookname:Foo|foo]].
• Short modules that are part of several different wikibooks can be written once and for all. After improving that module in the course of editing one book, all the other books immediately use the improved version.
• This doesn't require a separate database or software change -- it's already running at http://wikibooks.org/ .

Disadvantages:

• Without separate domain names or software changes (which are unlikely to happen soon) chapter pages are very likely to run soon into naming conflicts between books.

Note that both of the disadvantages may not be relevant for certain annotated texts. I.e. for specific texts with unique titles, which will be annotated only once, there are no naming conflicts. Therefore, no subdomains are required, nor any software changes, and normal wiki ease-of-use is fully maintained.

I think you mix up "no delimiter, no book title on subpages" with the next section "arbitrary delimiter", that is a blank space " ", or a section that still would have to be added. "No delimiter, no book title on subpages" means here that the bookname does not appear on every subpage, which makes it very likely that two books get into naming conflicts, even for annotated texts.

No delimiter, no book title on subpages, and separate domain names

One method is to use no delimiter at all, that is, for a Wikibook named bookname, and a subpage called subpagename, the article name is subpagename (i.e. the bookname does not appear). Also, each book is placed in a separate domain name.

World History
Civilization and Empires in the Indian Subcontinent  (<- this is a subpage of World History!)
The Industrial Revolution    (<- this is a subpage of World History!)

(World History pages have been changed in the meantime to namespace delimiter. The lines are kept as an example)

Vector Math (<- this single modules is referred to in the middle of the Geometry, Calculus, and Electronics books)
ASCII character set (<- this single module is referred to in the appendix of just about every programming language)

Advantages:

• Title of subpages does not get cluttered by long book title (but the book title is put in the domain name).
• Scalable, making it easier to split up wikibooks over more servers.
• No unrelated clutter in Special:Recentchanges, Special:Allpages, Special:Wantedpages, Special:Lonelypages, Special:Deadendpages, and Special:Categories. (Yes! We need this!)
• Normal wiki ease-of-use is fully restored: [[foo]] instead of [[Bookname:Foo|foo]].
• This doesn't require a separate database or software change -- it's already running at http://wikicities.com/ .

Disadvantages:

• This requires separate domain names: cookbook.wikibooks.org
• A module cannot be shared between books -- the Vector Math module is custom to each book it appears in. If ten people make ten different improvements to that module, those improvements are scattered over all the copies of that module, and it is hard to integrate them.

Arbitrary delimiter

Any character could be used as a delimiter, restricted only by the taste and imagination of the authors: " " (blank space), "-", "--", "," (comma), ";", .... All of these in combination with another blank " " (white space) either before, or after the delimiter, or both.

As You Like It    ⇒  As You Like It - Act III
Bicycle Repair    ⇒  Bicycle Repair Cleaning parts
Using GNOME       ⇒  Using GNOME : File manager

Advantages:

• Each author can easily please their tastes.

Disadvantages:

• It is difficult to work efficiently upon different books without a clear convention.
• It is not consistent across books.
  • Thus, it becomes a usability problem.

A combination

Use a combination of the above: For example place books into a designated namespace, but place pages on subpages.

Musictionary
Musictionary:Guitar
Musictionary:Guitar/Bass

Advantages:

• Could combine the advantages of namespaces (if they were really activated) and of subpages (link to parent).

Disadvantages:

• Makes very long titles for subpages.
• For new users this approach does not seem intuitive and simple at all. Since two different delimiters are used, it might be cause of confusion or false usage.

Other

Please place other methods here

Subhierarchy

As flat as possible

The naming of subpages should be done so that each subpage name reflects hierarchy, but does not introduce sub-subpage level of hierarchy. This should be done so that the subpagename together with the articlename sounds as natural as possible.

US History
US History:Pre-Columbian
US History:Civil War

Advantages:

• Chapters can be easily rearranged in the future. The emphasis is on the content of the subpage, not its structural location within the book.

Disadvantages:

• The structure of the book is not visible from the title. One needs to refer to the table of contents, or other navigational help.

As structured as possible

A book could be structured in several chapters, sections, sub-section, and so on. Subpages allow easily to build this kind of hierarchy, but one is not limited to the use of subpages: With any kind of delimiter, a structuring is possible. For namespace-like delimiters, it is possible by adding extra :subpagename sections, but this method is not mirrored in namespaces.

Geometry
US History
US History:Pre-Columbian
US History:Pre-Columbian:Aztec Empire
US History:Pre-Columbian:Mayan Empire

Advantages:

• Book structure is easily visible: One "knows" in which part of the book one is.

Disadvantages:

• The main demerit is that subhierarchies may make a book slightly more difficult to read or present.
• Another disadvantage is that it doesn't allow for a page to be in more than one location in the hierarchy of non-linear wikibooks. For example, Cookbook:San Francisco style Scallop Ceviche is a ceviche recipe, a main dish, an appetizer, a scallop recipe, and a California cuisine recipe, and could be structured under any of these. Gentgeen 22:12, 13 Mar 2005 (UTC)

Title on subpages

Use the full book name on subpages

A bookname scheme can be to use the same articlename on the contents and the book pages proper, ie bookname is the contents page and bookname:subpagename are on the subpages.

SA NC Doing Investigations              ⇐ bookname
SA NC Doing Investigations:Chapter 1
SA NC Doing Investigations:Chapter 2    ⇐ same bookname

Advantages:

• One (reader and automatic software) can easily see which subpage belongs to which book.
• Given the name of any subpage, I know the name of the book.

Disadvantages:

• Subpage heading might get very long.

Use a short book name on subpages

Another possibility is to use a long elaborate title for the book name, but a shorter title for the subpages, i.e. using a long bookname on the contents and a shorter shortbookname on the subpages. The shorter title should not be reduced to have the effect to reduce readability - for example, "IP:..." should not be used as a short title of "Introduction to Philosophy"; one reason why this is a bad idea is because it can be confused with a title such as "Inside Perl"?

Learning the vi editor                 ⇐ bookname
Learning vi:Basic tasks
Learning vi:Advanced tasks             ⇐ shorter bookname

Advantages:

• The long title can be more descriptive, without cluttering all sections of a book.

Disadvantages:

• Makes automatic extraction of book information more difficult.
• Subpages only work when the exact title is used on every subpage.

Numbers as chapters

Use chapter descriptions

Business English/Getting more practice
Business English/Phrasal verbs
Business English/Phrasal verbs/Get

Advantages:

• One knows about the content of the chapter.
• It is easy to insert new chapters between existing ones or change their order (important for the wiki process!)
• Chapters can be easily rearranged in the future. The emphasis is on the content of the subpage, not its structural location within the book.

Disadvantages:

• One does not know about the current position within the book => need for additional navigational structure.

Use chapter numbers

Computer Science:Algorithms:Chapter 1
Computer Science:Algorithms:Chapter 2
Computer Science:Algorithms:Chapter 3

Advantages:

• The structure of the book is emphasized.

Disadvantages:

• The number does not say anything about the content of the chapter.
• It is difficult to rearrange chapters or insert a new chapter between existing ones (move all higher books, or copy all content?). This is insofar severe, as wikibooks are expected to grow in the future.
• It is completely unusable in non-linear wikibooks.

Use chapter numbers and description

Macbeth - Act 5, Scene 1 - Dunsinane. Ante-room in the castle
Macbeth - Act 5, Scene 2 - The country near Dunsinane
Macbeth - Act 5, Scene 3 - Dunsinane. A room in the castle

Advantages:

• One knows in which part of the book one is.

Disadvantages:

• Difficult to insert new chapters.
• Long titles.

Personal taste and discussion

Please place advantages and disadvantages of the methods in the appropriate sections above, and put personal taste into here.

I think, with all the mess around currently, the definite way for the future is to have a clear recommendation for future books (which hopefully will outnumber the existing books at some point in the future), whichever that might be. Since subpages offer an automatic link to the parent page and (more or less) force to use exactly the same booktitle on all subpages of the book, my personal taste would be to promote subpages as the way to go, clearly recommending only 1 layer of substructure (no sub-subpages), and descriptions of chapters instead of numbers. --Andreas 09:37, 13 Mar 2005 (UTC)

The result of the below vote should not result in a mere recommendation - it should be policy. I have no real problems with subpages other than the hierarchy and the principle of least surprise comment that the ":" has that I've raised before. Dysprosia 10:36, 13 Mar 2005 (UTC)

My thoughts are at Help:Namespaces. I don't find either of the namespace cons very persuasive -- we can use more than 200 namespaces right now, and the software could surely be changed to allow for me (is there a technical reason it has to be at any fixed number?). TUF-KAT 21:49, 13 Mar 2005 (UTC)

Apart from the 15 standard namespaces, none of the additional namespaces listed on Help:Namespaces is actually really a namespace (Cookbook is none, Wikiversity is none... I know this because I restricted my Wikibooks:Top active SQL search to namespace "0", and Cookbook and Wikiversity are both in there - my list of books counts 400 titles by the way). I cite from Wikibooks talk:Namespaces#Policy on namespaces:

"With the current implementation, having too many custom namespaces is a bad idea - they all have to be manually entered in the MediaWiki configuration file. Also, deleting and renaming namespaces is quite a pain. So I suggest keeping the number of custom namespaces small, at least at first, maybe 5 or 6.--Eloquence" [2]

So we are really talking about "pseudo"-namespaces, that only look like namespaces but are not really (still, the pipe-trick works for them too: [[book:page|]] will display as [[page]]). Given that, it is just a matter of taste which symbol to use to delimit the bookname from the subpage name. The only true hierarchical support is given for subpages, which give an automatic link to the parent page. This option was not available when things were discussed on Help:Namespaces (since subpages have been enabled only recently for the main namespace on Wikibooks), but is available now, and might help the many new wikibooks that pop up every week by providing the basic navigation "for free". --Andreas 23:35, 13 Mar 2005 (UTC)

Subpage disadvantages

I put the following disadvantages for subpages which seem flavored by personal taste ("..are very annoying..") to the discussion section, and converted the points above to a more neutral tone --Andreas 08:55, 2 Apr 2005 (UTC)

• Hierarchy is often wrong. Anise is a spice, herb, and vegetable. Whisk is both a cooking technique (verb) and a cooking tool (noun). Subpages do not allow for this; they only support tree structures.

  This point should probably go under "flat vs. structured". As pointed out above, I can have a flat hierarchy with all delimiters ("/", ":"), as I can have a deep tree structure with all delimiters (e.g. Cookbook:Spices:Anise vs. Cookbook/Anise). --Andreas 08:55, 2 Apr 2005 (UTC)

  No, because the "/" delimiter is special. It has built-in wiki support that enforces a tree. This is no good.

• Subpages are very annoying if you wish to process wiki text as files. For example, one might save wiki text to files on a Linux system so that the grep command (or a slightly more complicated script) can be used. Having the "/" makes this awkward. Shell wildcard expansion fails, so the "find" command will be needed. Files can no longer simply be saved; a "mkdir" command will be required.

  If a structure is "annoying" or not probably depends on what you want to do, how many wikibooks you want to process, and so on. I agree, if you had scripts working with your cookbook, and after a change they don't work anymore, this is annoying, but imagine that each wikibook would have its own url (cookbook.wikibooks.org, kochbuch.wikibooks.org, howtobuildacomputer.wikibooks.org,...) and you want to process them - wouldn't you put the pages of each of those books into a separate directory before processing? (some pages might have the same name!) So, this is what the "/" delimiter automatically does for you! --Andreas 08:55, 2 Apr 2005 (UTC)

  I'd want to process just one book actually, the cookbook. What I don't want to see is Cookbook/Vegetable/Anise, Cookbook/Spice/Anise, and Cookbook/Herb/Anise. What are they going to be, symlinks? Duplicate copies? Hard links? In any case, this artificially enforced hierarchy is going to make a mess.

  What about Glossary/Anise? I'm not trying to change existing wikibooks, but find the most useful form for many few pages long wikibooks that pop up without a definite naming scheme. Since many beginning wikibooks even lack navigational templates, the best way for those new books would be to have an automatic link back to their main page, and enforce that all pages start with the very same bookname. This is what subpages do.

  I see that for significantly larger projects pseudo-namespaces make sense as well, that is why I suggest a double policy: Subpages for books that have a linear structure (you read them from the beginning to the end), and namespace-like for collections of items like the cookbook. What do you think about this compromise? --Andreas 06:11, 3 Apr 2005 (UTC)

  People keep raising exceptions as to why a scheme won't work. Whatever scheme (or schemes) is settled upon there are going to be special cases that don't work (and therefore require a workaround). I agree that subpages works well for linear books and namespace for collections so I think adopting both is a good idea. Mixing the two is obviously less desirable so a workaround may be required for a liner book that belongs to a collection (e.g. a linear programming textbook inside the programming namespace). --M.linger 6 July 2005 03:51 (UTC)

kelvSYC's thoughts on the issue: I believe good consistent organization is a must. Thus, the naming scheme should be related to the scheme used for templates/categories, etc. So my thoughts:

• Whatever the convention is, each and every existing Wikibook should be converted to the standard convention.
• A title with no delimiters, to me, implies a separate Wikibook. Categories should organize parts of books (eg. textbook answer keys) as well as books that are related (eg. Abstract Algebra and Linear Algebra should be categorized as "mathematical textbooks"). As it is entirely possible that books are part of other books, the category system should reflect that.
• Categories can also be used for, say, an automatic indexing feature (see Wikibooks Pokédex), but it should be avoided
• Only large overly general books deserve separate namespaces. Good examples would be Cookbook, Programming, and Game Guides and Strategy.
• Table of contents, indices, and all that should be colon-delimited if the book's title page does not contain them (eg. "Foo:Table of Contents", "Bar:Alphabetical Index" vs. "Baz/Chapter 1")
• Actual book content should be in subpages, whenever possible.
• For books with such a structure, a top-level subpage with custom up-links should be provided (provided we can hide the default up-links).
• The about pages (notes for contributors, etc) should be colon-delimited (eg. "Foo:About", "Bar:Contributers Notes").
• Bracket syntax should never be used.
• Books should be moderately structured: the hierarchy within a book should be as structured as possible, but flat enough so that names are not too long. (even if it means we have a very long page) Hierarchies should not be more than, say, three or four levels deep.
• All templates and categories specific to a single book should start with the name of the book. (eg. "Template:Foo:TOC", "Category:Bar:Pages on baz")
• For pages that are part of multiple books, put it as a subpage of one book and have all others redirect to it, and make custom up-links. Which book it should be part of should be up to discussion.

KelvSYC 05:51, 13 Apr 2005 (UTC)

I think that it is safe to say that we will adopt either the Bookname:subpage or the Bookname/subpage hierchy. I tend to go with the former because so many books use their own templates as navigation techniques, so the Bookname/subpage hierchy would look odd. Also, I think that since the other kinds of namespaces, such as Wikibooks: and Talk: and User:, etc. are done in this manner it will be intuitive to most users. As for substructure, I believe that should be the decision of the individual book writers- there are simply too many different circumstances. Some books are better divided into chapters only, some are better divided further.--Naryathegreat|(talk) 19:36, 17 Apr 2005 (UTC)

Voting

Ideally, the Wikibooks community should propose a method above and vote for a Wikibooks wide scheme for naming hierarchies. This will have the advantage of consistency and ease of use within Wikibooks.

Wikibooks should accumulate a number of naming hierarchy schemes and then set a vote, which should happen here.

New wikistats report for Wikibooks

I'm glad to announce a new report for Wikibooks, generated periodically by the Wikistats job. You'll find here an overview of books, their content and some stats. I discovered there are at least 6 naming schemes for chapters. This made it difficult to automate extraction of chapter names, so in some cases the grouping of chapters may look a bit odd. I'm sure this will improve when the ongoing discussion about standardisation of article titles bears fruit. Please look at Statistics per Wikibook Erik Zachte 15:18, 9 Apr 2005 (UTC)