Add help text throughout

[waldoj]

In the style of Richmond Sunlight, sprinkle explanatory text throughout the website. This is especially important on the law page. When the text needs to be hidden behind a UI element, display it with the qTip jQuery plugin, which is already in use within laws.php.

I've created a wiki page to store this help text while it's being written.

[waldoj]

More of this text really can't be written and implemented until we've had the time to kick the tires on the new UI. I'm moving this up to v0.9 (v0.8 is too close to being finished to move this up to that release) for resolution then.

[krusynth]

What more is needed here?

[waldoj]

I think basically the stuff on this wiki page. A bunch of this has been written and integrated already. I think I just need to turn it into a punch list here, and start writing it. I think it really needs to be stored in an external file, something that survives upgrades, because folks are going to want to customize it, e.g. to say "this is a regulation" instead of "this is a law."

[krusynth]

There are a bunch of different ideas on that wiki page. The main pieces are:

• [ ] Add inline help ( ? icon and text )
• [ ] Add on-page documentation that's always present.

Storing this in an external file is doable, we could just use a json file and dynamically include the definitions in. This is far easier if we avoid any on-page documentation, since it'll end up not getting picked up by search engines. (Unless we include it in the PHP, and I'd really really rather not have that extra cruft.)

and also:

Perhaps show slightly different text if the browser provides a third-party referrer?

This one seems like a bad idea to me. It will only show up for the first page and then disappear if they click to any other page. I understand the impetus here, but that violates the principle of least astonishment for me. Since we're just talking about a line or two of text, I don't think it's that big of a deal to always show this to all users.

[krusynth]

Great, so it looks like help.json already exists, and there are associated methods and modals already.

[waldoj]

Thanks, Past Us!

[krusynth]

That PR I just added provides all the scaffolding necessary to wrap this up. However, I still don't have most of the help text we need here - that wiki page just says like "hey write something for this." I don't feel super-confident with filling out most of this as described (IANAL), so I'm leaving that to @waldoj to fill in the gaps.

I'm also a bit concerned that what's in that wiki is a bit pedantic. E.g., this doesn't actually seem any more helpful to an average person than what's already there:

This is a law that is part of the Code of State, part of the Structure called 'Structure Name.' It is formally identified as '§ 12-345.67', but it has a friendlier title of 'Catch line.' Below is the text of the law.

---

To add help text, two things must be done:

• Create the documentation in the htdocs/content/help.json file.
• Add a ? icon button with a data-help attribute that matches the key from the help.json file. That button should look like this:

<a class="help helpbutton" data-help="history"><span>help</span></a>

[waldoj]

I just filed a pull request that provides what is IMHO the most important help text that's needed—an explanation of what one is seeing when landing on an individual law page, which is how most people enter the site. More help text is good and necessary, but of very little import compared to that law-page explanation, and so not necessary for v1.0.