Help!

By Garry Gibson on 14th June 2018

We all need a little help every now and then, right? If I can forget how to use screens that I actually wrote, it’s hardly surprising that others need a clue or two along the way sometimes when using our stuff.

Ok, so we want to give people some info on how to use the system. Understood.

Really?

No, not quite understood. Yet.

In what form? A big printed manual that procurement departments like to see so they can tick a deliverables box? Whilst that might help us get paid, it’s not of any actual use to the end users. How about we explain all the configurable options in a big page of text? Nah, even I won’t read that. After a few cups of coffee and a bit of pondering I came up with a few basic requirements:

  • Get something (anything) in place ASAP to store the actual help content that we need to start creating soon.
  • Allow for different forms of help – i.e. FAQ, screen level, field level etc.
  • Allow for the info to come from different sources, such as us as the supplier, client user champions and maybe the end users’ own ‘notes to self’.
  • Easy to implement on new screens for developers and content authors.

As with most aspects of SignedUp, we aim to write code that is a simple yet flexible starting point that can evolve over time as we learn more.

Sounds like the most important thing right now is to build something that lets us start creating the help content, which in practice is the easiest bit (assuming we get the data model right). That’ll ‘just’ be a table or two to store the help, and some simple admin screens over the top to add/edit/delete the data.

Database tables.. check.

Admin screens… almost check. Do we allow plain text, or rich text with formatting like bold fonts, lists and the like? Yeah, let’s go with rich text formatting. We’re trying to make something that’ll be engaging and useful. Pages of plain text aren’t that.

What about linking the help to actual screens? How do the help authors do that? Well, it turns out we already have a list of all the screens in the system that the permissions code uses. That’s handy. We can link help text to those ‘action’ records and reuse that list. Which has the added advantage of being auto-generated by the system so developers don’t have to maintain it when new screens are added. (We still forget to add the permissions in the admin config, but that means it’s secure by default.)

Right – basic structure and admin done, now what about actually showing the text to users?

Many moons ago our man-on-the-ground Karl was showing the users some mock ups which had what looked like Post-It notes on, describing the intended functionality. The users said it would be great if the system could actually do that, so I squirrelled away a little proof of concept using CSS to see if we could present stuff that looked like stuck-on post-its. Sounds like it might be fun to link that up with our emerging help text content.

But, we don’t want adding help text to screens behind the scenes to be a faff, or developers won’t do it. (newsflash)

How about each screen has a quick check to see if there’s any help for it as it fires up? Easy enough to implement as an ActionFilter, with the actual HTML bits in the single overall layout page.

Now in order to add help text to a screen the developer just needs to tag the Controller Action as being able to have help text added (oooh, new thought – we need to limit the list of screens shown on the create / edit screen to only include those that have been appropriately marked)

 

That’ll be enough now to prove or disprove the concept and help us work out what else we need to add to it.