Organisation of help pages

[richardofsussex]

The main menu has About and Help, separated by other headings (Volunteer and Logout/Member). There are other help pages, but they can only be accessed if you happen to click on the 'right' link. There is no place you can go to to get a sense of all the help that is available. Also, I would question the utility of having two routes down into [different] help on the main menu, randomly separated from each other. I would suggest, as a minimum, a 'help elsewhere' contents list at the bottom of the main Help page with links to all the help pages. Ideally, the Help Menu item would also have sub-menu options appearing below it when hovered over.

We also need to document exactly what help pages we plan to produce for MVP.

[AlOneill]

Hovering would exclude those who cannot do so, whether through disability or a broken pointing device.

[richardofsussex]

I agree: a proper sub-menu would be better, but I don't know how straightforward that would be to implement.

[richardofsussex]

Reviewing the pages on the beta site, I see that some links from the FAQ page take you out of the BMD2 site and into the generic FUG site, without flagging that they are doing so. Given the similarity in layout of the help pages on the two sites, this can cause confusion. (It certainly confused me!) Links would be OK if flagged as being to an external site.

[richardofsussex]

I have attempted to document all the links between help pages to pages within the FreeBMD2 site: https://drive.google.com/drive/u/1/folders/1qcuyMN3_jHoXQuDPBdGlSNNWHTJe9m2C.

Apologies for the scruffy Paint-generated diagram ... also for the fact that the URL doesn't work (thanks, Google Docs!). It's the file BMD2 Help Pages structure.png in the list.

[richardofsussex]

I've done some work on implementing a framework for help within Rails, so that Refinery isn't required (and could be dropped from the FreeBMD2 Rails implementation). The general idea is that the help is divided into 'chunks' - each one a potentially free-standing mini-document. These will be Rails 'partial' documents, containing simple HTML markup. Each help page on the web site is created by a document which pulls in the required 'chunks' in the desired order:

I have written a procedure create_island which generates the 'On this page' and 'Help Pages' islands from structures declared in the Help data model, e.g.:

[richardofsussex]

The result looks like a standard Refinery help page:

[richardofsussex]

The idea is that as much as possible of the 'structural' HTML in the page is generated programmatically, rather than relying on the help page author to get it right. (I have more work to do on this front: each call to render a 'chunk' needs to be called from a function which wraps it in a suitably-encoded <div> element.)

Another advantage of this approach is that it gives us flexibility in how we put the help pages together. We can reorder 'chunks' easily, and/or move them to a completely different help page.

A third advantage is that contributors other than (our 2!) Rails developers could author the 'chunks' externally, using the HTML-enabled editor of their choice and some simple guidelines. All @Vino and/or I would have to do is to rename the files and add them to the appropriate folder within our Rails setup.

Finally, having these focused 'chunks' of helpful advice opens up the possibility of displaying them in other contexts, e.g. as pop-up help.

[richardofsussex]

My original ambition was to develop a completely 'data-driven' way of rendering the help pages, but Rails prevented this by refusing to allow multiple render operations within a single block of code.

[richardofsussex]

The individual 'chunks' of HTML can be uploaded to Google Drive (see https://drive.google.com/drive/u/1/folders/1EQBx_Vi_1bD8xwb_hVn9K6Oh7JRAEm8F?ths=true):

and edited from there, using the online Text Editor app (which knows a little about HTML):

If the files are given the suffix .html (as against .html.erb, which we normally use), the Text Editor can work with them, and so can Rails. This removes the need for file renaming.

[richardofsussex]

This approach makes it straightforward for non-programmer volunteers to update the help, without having to tangle with Refinery. In fact, it removes the need for Refinery completely.

@Vino-S and/or I would simply copy across updated 'chunk' files into our Rails authoring environment and deploy them.

[richardofsussex]

In response to the comment that the screenshot above doesn't match the Version 5 wireframe, I have updated the top-level headings/links so they match, and moved the sidebar above the 'On this page' one. The top-level options are visually different from the wireframe, but functionally they do the required job: navigating to the page indicated by the link:

In fact, I now have a complete set of top-level help pages, although most of them lack content and therefore the 'On this page' links won't, in general, work.

[AlOneill]

I notice that the visual hierarchy of the headings does not look quite right: "Help: Search" looks the same size as both "Getting started" and "The FreeBMD database". If "Help: Search" is an h1 then it should look like one.

[richardofsussex]

Good catch: thank you:

[richardofsussex]

Meanwhile, @Vino-S has developed a Javascript-powered mechanism which allows all the help to be delivered as a single HTML page, but with only one (top-level) <section> displayed at a time. By clicking on the navigator, the user can choose which part of the help is displayed.

From the user's perspective, this is functionally identical to having a number of separate top-level Help pages, with the navigator providing simple links to each top-level page. The Javascript-based approach offers quicker switching between help pages; conversely it will only work if the user has Javascript enabled.

[richardofsussex]

I suggest that the work that Vino and I have done can be seen as complementary.

My island-generating code can still be used to produce the 'On this page' islands, even if it is not required for the top-level navigator. (The motivation behind this is to generate as much of the required markup as possible programmatically, rather than relying - as we do now - on hand-entered HTML, hoping that it will always match our conventions.)

The idea of creating static HTML pages and copying them to Google Drive for authoring and updating could be seen as a strategic shift. It removes our dependency on Refinery, which is obsolescent and which does not offer a WYSIWYG framework supporting our markup conventions.

[richardofsussex]

Further to the above, I have discovered how to wrap authors' HTML chunks into a <div> with suitable attributes. It involves declaring a template, e.g.:

and then invoking it when rendering the HTML as a partial:

Note that local parameters can also be passed to the layout template, e.g. id and title of a section.

One idea is that the HTML's filename could be passed in, and used to create an 'edit this section' link iff the user is logged in. This would make this approach start to look like a user-friendly alternative to Refinery.

[richardofsussex]

To summarize the issue:

• Refinery is obsolescent/under-supported
• Refinery's WYSIWYG support offers no help towards creating HTML markup which matches our conventions
• the proposed approach will ensure that the high-level markup of each page is correct, by adding it programmatically
• the approach involves splitting a single monolithic help page into manageable chunks, each about a well-defined topic
• Rails developers will need to set up the framework for each page, but authors will then be free to create and update help text within the 'chunk' documents provided
• the same technique could be used elsewhere on the site, where there is running text within a page which might be updated from time to time

[AlOneill]

@richardofsussex
Another thing that struck me, but I forgot to mention, is to wonder why you have put the menu of other pages ahead of the "On this page" menu? To my mind it seems more logical to put "On this page" ahead of the other pages, as per FreeREG volunteer help pages. The inroductory paragraph should reassure the user that they are on the correct page for their immediate needs.

I guess you are interpreting Kristina's wireframe and that the previous way of looking at things is now obsolete?

[richardofsussex]

I don't know about 'obsolete' - we could usefully talk this through. I was simply trying to demonstrate that the approach I am suggesting offers greater flexibility for tweaking the way the page is arranged. Also that we could mimic the layout suggested in the wireframe using my approach.

[richardofsussex]

Having viewed @Vino-S's code I can confirm that she is doing a better job than I managed, with the generation of the navigation 'island' for the top of the page. The island is generated by using Javascript to scan the structure of the page. I think this would still work if the page content was generated by Rails rendering a sequence of 'partial' pages, as per my suggestion. The layout template used by the 'partials' could ensure that each section of help has the appropriate wrapping structure, id, etc.

[richardofsussex]

Meanwhile, in response to @DeniseColbert's point that volunteers would need a WYSIWYG HTML editor if they were to be expected to create or update help page content, I have spotted HTML Editor for Drive: