#421 Guidelines front pages are confusing

[Martin Holmes]

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:

<http://www.tei-c.org/Guidelines/P5/>

from which you can navigate to the online version here:

<http://www.tei-c.org/release/doc/tei-p5-doc/en/html/index.html>

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:

<http://www.tei-c.org/release/doc/tei-p5-doc/en/html/index-toc.html>

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:

<http://www.tei-c.org/Guidelines/>

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]

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]

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]

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

http://web.uvic.ca/lancenrd/tei/

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

[Kevin Hawkins]

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]

We have two pilot pages which have generated some discussion:

• http://web.uvic.ca/lancenrd/tei/
• https://sourceforge.net/p/tei/feature-requests/_discuss/thread/63223f7a/297e/attachment/index-toc.pdf

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?

Keep:
KH, JC, LB, DS
Lose:
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

[Syd Bauman]

• 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]

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

http://web.uvic.ca/lancenrd/tei/

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]

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."

[Kevin Hawkins]

I imagine recoding all of this in the build process will be quite a task. But while you're deep in the code, you might see if you can take a whack at (1) at:

http://sourceforge.net/p/tei/bugs/426/#6bcf

As in the following comment, Sebastian wasn't able to fix it:

http://sourceforge.net/p/tei/bugs/426/?limit=10&page=1#b2dc

[James Cummings]

Should this ticket not be closed?

[Sebastian Rahtz]

yes, done

[Martin Holmes]

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