#421 Guidelines front pages are confusing


I initially raised this issue during the Council telco in December, and was tasked with asking for feedback on TEI-L. I've now done that, and I'm raising a ticket to summarize the responses. First, the problem:

If you go to the P5 Guidelines right now, you'll initially hit this page:


from which you can navigate to the online version here:


This index.html page has links to all the prefatory material, some links
to other related sites such as the SourceForge repository, and "Some
Popular Sections", a list of a few chapters in the main Guidelines. It
also links to the full Table of Contents:


which is what it says it is.

I've noticed in workshops that this three-stage entry process confuses
people, and in particular, the intermediate page with its "popular
sections" is not very useful. Even more confusingly, if you click on the
main menu "Guidelines / P5 Guidelines / -Table of Contents", you go to a
completely different page:


I received five responses, summarized here:

a) (2 votes): merge <http://www.tei-c.org/release/doc/tei-p5-doc/en/html/index.html> and <http://www.tei-c.org/Guidelines/P5/> into one single page (and leave the ToC as it is).

b) (1 vote): merge <http://www.tei-c.org/release/doc/tei-p5-doc/en/html/index.html> with the ToC putting "Versions of the Guidelines", "Some Popular
Sections" and the language section on a separate column on the right.

c) (1 vote): The extra index.html page is confusing, so get rid of it.

Comment from Lou:

One thing I like about the "short" index page is that it puts the language switches up top, so people realise the Guidelines are available
in multiple languags. If we change things, I hope that will continue to be the case for whatever replaces it.

Nobody wrote to defend the multiple pages. I would go for b) myself, and b) also satisfies c). Many people say they just bookmark the ToC page once they've found it, and go directly there from their bookmark.


  • James Cummings

    James Cummings - 2013-01-08
    • milestone: --> AMBER
    • assigned_to: nobody --> martindholmes
  • James Cummings

    James Cummings - 2013-01-08

    Although the submitter, assigning to martindholmes to shepherd through getting TEI Council agreement. Setting as Amber for now since I think we want to be very clear on what change we want to make so needs more discussion. -James

  • Kevin Hawkins

    Kevin Hawkins - 2013-01-29

    In an email to the TEI webmaster, Serge Heiden suggested the following:

    ** http://www.tei-c.org/release/doc/tei-p5-doc/en/html/index.html
    - I would add the "4 Default Text Structure" section entry in the
    "Some Popular Sections" list because new users very frequently
    begin there, and I have been reported that it is difficult to get to
    the right page on text structures (...)
    - I would homogenize the "Versions of the Guidelines" list:
    -- "Table of contents" -> "HTML for Online Access"
    -- "PDF" -> "PDF for Reading and Printing"
    -- "Getting the most recent version" -> "XML-TEI source Introduction"
    -- "Sourceforge Subversion Repository" -> "XML-TEI source Access"
    -- "Bug Reports, Feature Requests, etc." should not be in this list but
    in its own section, or be removed
    - The "Sections in this document:" top left list is the TOC of the Guidelines Front Matter,
    but 1) is not on the same level as the "Versions..." and "Some Popular..."
    sections 2) repeats "v. About These Guidelines" and "v A Gentle Introduction to XML"
    section titles found in the "Some Popular..." section which is confusing reading.
    I would:
    a) suppress the misleading "Sections in this document:" title
    b) just let the i, ii and iii sections titles

  • Martin Holmes

    Martin Holmes - 2013-05-14

    I've now created a unified TOC document for people to look at here:


    I've tried to take into account all the feedback and suggestions we got.

  • Kevin Hawkins

    Kevin Hawkins - 2013-05-15

    Martin, thanks for the good work on getting this going. I have never liked how we currently show the back matter in its own column on the right rather than under the body text. I recall someone saying this was done because some of the back matter is stuff that people visit often. If so, I think these sections should be added to the list of popular sections.

    In the attachment I have down my own fast mockup. I have not added any sections from the back matter not already in the list of popular sections, but I would support doing that for any that people feel they need to access often.

  • Martin Holmes

    Martin Holmes - 2013-05-17

    We have two pilot pages which have generated some discussion:

    and we have a call out for answers to the three questions below, so we can get consensus from the Council on which directions to go in. These are the questions with answers so far:

    1. Do we want two columns however wide your screen is, or do we want
      three columns collapsing to two if there's not enough room for them?

    Two columns:
    KH, BB, LB, GB, SB
    Three collapsing (responsive design):
    MH, JC, DS, SR, HC, RW, EM

    1. Do we want to keep Some Popular Sections?

    KH, JC, LB, DS
    MH, BB, GB, SR, HC, RW, SB, EM

    1. Do we want to include the alternative output formats (PDF, ePub,
      Mobi) as list elements like the rest of the TOC (as in my mockup, the first link above), or as links in a horizontal list across the top (as in Kevin's)?

    As bullet list:

    As horizontal list of icons:
    KH, MH, BB, JC, LB, GB, SR, HC, RW, SB

    No preference:
    DS, EM

    Last edit: Elli Mylonas 2013-05-24
  • Syd Bauman

    Syd Bauman - 2013-05-23
    • As for original question, I guess I mildly prefer (a), but don't really care much as long as we make it overall simpler
    • as for Martin's questions 6 days ago:
      1. [2 vs 3 col?]: Don't know enough to care; if pushed, I guess mild preference for 2 cols
      2. [keep popular?]: Certainly in their current form I'd lose them, unless someone can provide evidence that the items in that list are actually popular. Perhaps “Some useful reading and entry points” or some such. But even so, once we don't have such a confusing entry mechanism, I'd think the ToC will suffice. People will find the entry points they like (and their browser will show them in a different color, if recently visited) and bookmark them as they like.
      3. [vert or horiz other formats]: mild preference horizontal
  • Martin Holmes

    Martin Holmes - 2013-05-23

    Based on the feedback, I've created a new mockup:


    This goes for responsive layout (3 columns collapsing to two), dispenses with Some Popular Sections, and puts the links to PDF etc. as icons across the top. It also occurred to me that we could put Front and Back Matter in one column, with Body in the centre column, so I've done that; it has the advantage of making the Back Matter easily accessible for folks who use it a lot like me, while still foregrounding the Body.

  • Kevin Hawkins

    Kevin Hawkins - 2013-05-23

    I like it! While it doesn't keep the sequence of front, body, and back, you don't easily miss the back matter in the way you do now. While I would still like some sort of shading behind the "TEI sourcode" block, I won't stand in the way of progress.

    You'll want to give some padding to the right of "Version 2.3.0. Last updated on 17th January 2013."

  • James Cummings

    James Cummings - 2013-11-09

    Should this ticket not be closed?

  • Sebastian Rahtz

    Sebastian Rahtz - 2013-11-09
    • status: open --> closed
    • Priority: 5 --> 1(low)
  • Sebastian Rahtz

    Sebastian Rahtz - 2013-11-09

    yes, done

  • Martin Holmes

    Martin Holmes - 2013-11-09

    Closing this -- it's been implemented and is in the last release.

  • Martin Holmes

    Martin Holmes - 2013-11-09
    • status: closed --> closed-fixed