Creating Index Pages

Group the pages into logical groups, and put them under headings.

• Under each group, pages are listed in a bullet list.

  • If there are sub-pages, list them in nested lists.

• Each page gets an annotation after the link (see below for examples). The annotation provides a basic description of what’s in the page, above-and-beyond the page title.

  • Annotations are a great place to label pages as “UNDER CONSTRUCTION,” “DEPRECATED,” or even “this page is kinda old.”

  • Annotations can be updated without having to update the underlying page.

  • They are also great places to provide basic definitions or expand common acronyms.

When new pages are created, whoever created them can add a link to the top page. They get to decide what group heading the page falls under (or whether or not to create a new group heading) and how to describe it.

Discoverability, discoverability, discoverability. By laying out the entire space hierarchy, you make it easier for someone to find what they are looking for at a glance.

• It’s much nicer to find a needle in the haystack if all the hay is displayed in neat rows.

• Readers can scan through the whole space contents without needing to keep a navigation stack in their head.

• It’s still easy to find what you’re looking for if you don’t know how to describe it (mostly because of link annotations). This corrects for the biggest failing of wiki search functionality.

• The front page actually teaches users about the space’s contents, rather than just assume they already know.

• For a space with a large number of pages, the front page will be huge. This is a good thing! Do not hide complexity behind hierarchy.

The “page tree” macro could be used to produce an automated list of every page in the space, including all nesting. Furthermore, each page could use the “excerpt” macro to declare its own annotation, and the page tree could be configured to display that.

While this would make the top-level page easier to write, it has a few flaws:

• The pages would not be grouped under logical headings.

• The pages would be sorted in a probably-naive order.

• Annotations would need to be manually added to each page (more edits) and maintained as such --- this takes more pain, especially if applying this to an existing pile of pages.