Creating Index Pages

 

The front page of a wiki space should act as “table of contents,” and more. The ultimate goal is to have complete visibility of every page in a space, with descriptions.

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.

This page acts as an example. Pretend the below describes the pages in a real confluence space.

These aren’t real pages at all, just a visual example.

  • [fake link] page alpha --- documents the new process for Foo --- UNDER CONSTRUCTION

  • [fake link] page beta --- big page describing the current process for Foo

    • [fake link] page b2 --- for Foo Bars --- this page is kinda old

    • [fake link] page b1 --- for Foo Bazzes --- has an excellent writeup for the blanket legacy process

    • [fake link] page b3 --- for Foo Quxxes, and the definitive list of project dependencies

  • [fake link] page gamma --- show how to so something else --- DEPRECATED

  • [fake link] page omega --- describes something about MFEs (micro frontends)

Standard Sample Pages

These are real pages that confluence created by default for this space.

Staging Area for readthedocs

Working Group Policies