how-to-split-pages

From Microformats Wiki
Jump to navigation Jump to search

how to split pages

In general please avoid splitting pages.

If you are the primary author of a page, or feel strongly about the need to split a page, here are some guidelines that should help.

Editor: Tantek Çelik

first think about making things easier

When deciding how to split pages, consider doing so in ways that make it:

  • easier for new contributors to add content
  • easier for people to iterate on the content
  • easier for people looking from a real world perspective to find the information.

second add notes

If you do see a need to split a page which you are not one of the primary authors of, first add notes in the page in-place where you think splits need to occur, and how you think they should occur, before making any split.

This is especially important if you are not one of the primary author(s) of the page, so that the primary author(s) have a chance to see and follow-up with refinements/changes on how the pages should be split.

good ways to split

From experience we have found several good ways to split pages.

Perhaps the best way to split pages is to see the first section - think about making things easier for both editors and readers.

One way that seems to work well, especially for examples in the wild pages, is to separate by:

  • new examples - don't make a new page, just keep this as a section near the top of the main examples in the wild page so that new folks coming to the page to add new examples can easily see where to do so, and then easily edit the page to do so.
  • pages for each higher level category of examples. create pages for each higher level category of examples, and then create a small section at the top of the main examples in the wild page that simply links to those pages in an ordered list / outline (not with separate headings for each category) of bolded links to those separate pages, ordered by most commonly useful general categories of examples down to the more specific or esoteric examples in the wild. This works well for new users who find the examples in the wild page, and can quickly see the outline of relevant categories of examples to look at which resembles a table of contents, and can easily navigate to the page for the specific category.

avoid bad splits

Unfortunately we have experienced a few folks doing bad splits on wiki pages. We can at least describe and document these bad experiences so that we a) learn from them, and b) avoid such behaviors in the future.

splitting by state of content

One type of split that's been performed that's been particularly counterproductive is the split by state of content.

A specific example of this was the early 2008 splitting of hCard Examples in the wild into

  • hcard-examples-in-wild-pending
  • hcard-examples-in-wild-with-problems
  • hcard-examples-in-wild-reviewed

This split was flawed and counterproductive for several reasons, all of which hurt usability and thus hurt accessibility as well.

The result was reduced community contribution rates to that content/page(s) dramatically. Over the course of about 8 months after the split was made, from 2008 mid January to mid September, not counting the creation of the separate pages, there were:

The following user contribution/edit scenarios were negatively affected in the following ways, which likely resulted in the above-noted reduced participation rates:

  1. "add a new example in the wild" scenario was made more difficult
    • Unobvious to new users where to add. For new folks coming to the hCard Examples in the wild page, this split made it less obvious where to add new pages with hCards.
    • Multiple clicks. For anyone looking to add their page with a new hCard 1.0 to the examples in the wild page, even once they found where in the hCard Examples in the wild page to add a new example, they now had to click another link and load another page, wait, and then look where on that page they should add their new example.
  2. "note problems with a new example" scenario was made more difficult
    • Editing more than one page required. Because "pending" and "with problems" pages had been separated, when a community member reviewed a new example and found problems with it, they had to edit both pages.
    • 3 edit steps turned into 8 edit steps. Instead of just being able to: edit the examples page, note problems in-line with the example (e.g. perhaps with nested list items), and save, they had to instead do the following
      • edit "pending" page
      • note problems with the example
      • extra step: cut that content
      • extra step: edit the "with problems" page
      • extra step: find the right place on that page to insert the content
      • extra step: paste the content
      • extra step: save the "with problems" page
      • save the "pending" page
  3. "resubmit example for review" scenario made more difficult
    • Editing more than one page required. Because "with problems" and "pending" pages had been separated, when an example author fixed a new example with reported problems and wanted to resubmit it for review, they had to edit both pages.
    • 3 edit steps turned into 8 edit steps. Instead of just being able to: edit the examples page, note that problems had been corrected (e.g. perhaps with nested list items), and save, they had to instead do the following
      • edit "with problems" page
      • note corrections to problems
      • extra step: cut that content
      • extra step: edit the "pending" page
      • extra step: find the right place on that page to insert the content
      • extra step: paste the content
      • extra step: save the "pending" page
      • save the "with problems" page
  4. "review and categorize example" scenario made more difficult
    • Editing more than one page required. Because "pending" and "reviewed" pages had been separated, when a community member reviewed a new example and found it ok, and determined a category for it, they had to edit both pages.
    • 5 edit steps turned into 7 edit steps. Instead of just being able to edit the examples page, cut the reviewed example, determine what category section to put it in, paste the example, save the examples page, they had to instead:
      • edit the "pending" page
      • cut the example
      • extra step: edit the "reviewed" page
      • determine what category section to put the reviewed and categorized example
      • paste the example
      • extra step: save the "reviewed" page
      • save the "pending" page
  5. "find illustrative examples" scenario was made more difficult
    • Unobvious to new users where to look. For new folks coming to the hCard Examples in the wild page, this split made it less obvious where to look for illustrative examples of a specific type (e.g. individuals, businesses, speakers listings). It is very unobvious to think to look at "reviewed" for such examples, because the state of whether it is reviewed or not is not the key detail that such folks are looking for.
    • Multiple clicks. For anyone looking to for illustrative hCard 1.0 examples in the wild to learn from, even once they found where in the hCard Examples in the wild page to look, they now had to click another link and load another page, wait, and then look where on that page they should look for such examples.

related