Documentation: "table of contents" consistency

[dlmurphy]

There are currently three different formatting choices we use for dealing with lengthy pages throughout all of our guides. These differing solutions are inconsistently applied, and create confusion when navigating the guides. Here are the three formatting options we've used:

Option A. No table of contents. This can be problematic for longer pages. Without any navigational aid, a user can get lost in all of the headings and subheadings.

Option B. A landing page of only the table of contents, with subpages displayed in the left navigation bar.

Option C. A table of contents box displayed at the top of the page, with the page's full content beneath it.

I believe that we need to choose one format and use it consistently throughout the guides so users don't have to figure out three different ways of navigating them. I believe that option C is the best of the three, but I would like to include this question in a future usability test to get users' input.

[jggautier]

Another difference between B and C is that each section in b, the Tabular File Ingest Page, has it's own page, which might be a ideal.

[dlmurphy]

On reflection, I believe option C to be the clear best choice for our docs for two reasons:

• Breaking up doc pages into further, granular subpages reduces the user's ability to use ctrl + F to find search terms of interest.
• Providing a table of contents at the top of the page allows for quick orientation on the page and navigation. All headers should be clickable to take users back to the table of contents, allowing for easy navigation

This approach is supported by this article on technical writing and its attendant presentation. I'd be comfortable going forward with these changes without having to specifically UX test them.

[pdurbin]

I just made pull request #3854 and moved this issue to Code Review at https://waffle.io/IQSS/dataverse

I also set up a Jenkins job that polls the branch behind that pull request every hour and puts an HTML version at http://guides.dataverse.org/en/3796-guides-table-of-contents/

[pdurbin]

@dlmurphy and I discussed pull request #3854 as of da2cda4 and he plans to think about and potentially work on moving the content of small pages such as http://guides.dataverse.org/en/3796-guides-table-of-contents/user/tabulardataingest/stata.html into their parent page. Sometimes it's nice to be able to glance at a URL to see where I am but for me user/tabulardataingest/stata.html and user/tabulardataingest.html#stata are relatively equivalent.

We also discussed how http://guides.dataverse.org/en/3796-guides-table-of-contents/api/native-api.html is quite long and how it would be nice to break up the Native API page into separate pages, similar to how the Search API has room to breathe on its own page. This is out of scope for now and we're already tracking this issue at #2174.

There's sort of question of if long pages are the enemy or not. http://guides.dataverse.org/en/3796-guides-table-of-contents/user/dataset-management.html is long but we're ok with that for now.

[dlmurphy]

Re: long pages as enemy, my feeling is that the ideal page is long enough to explore all relevant aspects of one discrete issue. If that means that a page is somewhat long, then that's OK; users can always use in-browser search or the table of contents/page headings to find the particular aspect of that issue that's most relevant to them. In rare cases where a page like this is unreasonably long, I think it's alright to break it up into two pages if there's an intuitive and sensible way to split it conceptually. In my opinion, there's no hard-line rule on this; it's something that needs to be evaluated on a case-by-case basis.

[dlmurphy]

(I'm currently working on altering the layout of the Tabular Data File Ingest user guide page to get it to conform with the "Option C" format I laid out in the original post)

Edit: While experimenting with this altered layout, I opted not to do this after all. Made more minor formatting changes to make the page fit with the rest of the guides.

[dlmurphy]

-Added a label to all within-page tables of contents - "On this Page:"
-Moved within-page tables of contents so they're positioned below the page's introductory text but above the first subheading, much like a Wikipedia page.
-Bolded the "Contents" label on all index pages.
-Added a blurb in the "Documentation" section of the Developer Guide explaining how to create and properly position a within-page table of contents.
-Made assorted other tiny changes/fixes to get all pages' tables of contents formatted and positioned consistently.

[pdurbin]

@dlmurphy "On this page" doesn't make much sense for a PDF or an ePub. Please check out the screenshot below from http://guides.dataverse.org/en/3796-guides-table-of-contents/Dataverse.pdf

Note that we don't advertise the fact that we create PDF and ePub versions of the guides, but we'd like to some day, which is why #2148 is still open. I like your idea of adding a word or phrase to explain what the box is. Maybe we could the word "Contents" like Wikipedia does:

[pdurbin]

@dlmurphy I figured out how to define a variable in 2739c72 and changed it everywhere with ack -l 'On this page:' | xargs perl -i -p -e 's/On this page:/|toctitle|/'. Please let me know what you think.

Here's where |toctitle| is defined once in the code:

dataverse/doc/sphinx-guides/source/conf.py

Line 431 in 2739c72

.. |toctitle| replace:: Contents:

Sphinx calls these "substitutions" and here are there docs on it:

"If you want to use some substitutions for all documents, put them into rst_prolog" -- http://www.sphinx-doc.org/en/stable/rest.html#substitutions

[pdurbin]

Oh, and to be clear, I changed "On this page:" to contents to be more PDF-friendly. However, if @dlmurphy or others want a different word or phrase, you are welcome to change it in conf.py. Mostly I just wanted it to be defined in a single place so we can easily change it when we start promoting the PDF and ePub versions of the guides.

[dlmurphy]

That's a great point about the epub and pdf versions. I'm fine with using "Contents:" as the label.