DT Change and improve text for HELP page

[richpomfret]

Improve text MVP quality text on Help page. May take a couple of iterations!

• [ ] add header, side bar, etc. for CSS.
  • [ ] needs to refer to the screens and processes on FreeBMD2, not FreeBMD1
• [ ] accessibility

[PatReynolds]

Addigning @ComfE-2662 as now being undertaken by Philip and others on the development team

[PatReynolds]

Hi @PhilipClarke712 could you switch the first two sections of 'Help' please - I think that people will want to see information about searching before information about accuracy.

[PhilipClarke712]

@PatReynolds Yes, I will do that today on test3 on a Draft page. That is less than five minutes work (unless I break something). I will get into trouble if I change the Help page since that is not a Draft page (so changes have to be signed off).

[PhilipClarke712]

Hi @AlOneill, As discussed elsewhere, could you review https://test3.freebmd.org.uk/cms/help/draft-help-1st-interim-version .

It is a reworking of a copy of the current Help page: no new content has been added other than adding on-page-hyperlinks and outline-hyperlinks to other pages, some of which are interim versions.

I've removed content relating to facilities (on FreeBMD1) that test3 does not currently offer - so at some time in the future it will need to be revised and resubmitted (normal maintence).

It has outline-hyperlinks to other five or six pages (perhaps more), so I will be send them along quite soon. It also has a working hyperlink to the About page.

[AlOneill]

@PhilipClarke712 review underway.

I was a little disappointed to see the non-alignment of the leading paragraph in the browser — that sort of thing should be jumping out at you! Also, you did not validate the HTML — the use of a validator to find errors is a great way to learn as well as a useful tool for assessing a page.

[PhilipClarke712]

Hi @AlOneill

Thanks for your two comments.

1. I totally forgot to use a validator, thanks for reminding me that I should use it.

2. I can see the non-alignment of the lead paragraph now; it's the sort of thing that I might do in a text-file by using tab and shift together. I don't know how to left-shift a paragraph using html tags, so I don't know how to un-do it.

Having gone in now and looked at the html of all three copies of Help (two drafts and the non-draft), the thing that strikes my attention is that on this draft page, the leading paragraph (class = lead) appears immediately after the tag line "article id="top" class="grid"" . The current live Help does have an empty paragraph (class=lead): and in respect of the html it sits immediately below the side navigation panels.

With the help of this "spot light", it seems likely that I put my lead line immediately below the tag line "article id="top" class="grid"" .

I have never used the "article" tag-line before, but I half remember you saving earlier this year that Refinery was going to put a "Top of page" code in automatically, so perhaps that is why I put my lead immediately after it. I would go further than that, none of the pages that I have produced have the tag "article" in them. I've also looked at pages of mine in refinery that you have Reviewed earlier this year and they do not have the line "article id="top" class="grid"". Your page Marking up pages in Refinery does not appear to have any "article" tags and neither does the page A typical Refinery page .

So could the code "article id="top" class="grid"" be the cause of this left-tabbing; and are "article" tags needed on Refinery pages?

3. For your convenience I've added a copy of the output from validator.w3.org Showing results for contents of text-input area - Nu Html Checker.pdf

It does not like a table being embedded in an unordered list and it lists that as an Error. I believe all the other errors, such has not specifying that the language is English and not specifying Doctype, is due to me copying the body of the html into the checker and not including any header lines.

Do you wish me to supply validator.w3.org printouts for every page that I submit from now on?

[AlOneill]

@PhilipClarke712 it's not the HTML elements that are the issue with the non-alignment, but the CSS. Once a floated grid is open, its children must have the class grid__item. I will solve the issue by placing the lead paragraph ahead of the grid, as per usual. And I'll replace the article element with a div as the former is not quite appropriate here (blind copying strikes again!).

There is no need for you to include the validator output — simply validate your markup and act on the results. The Markup Guide describes a way to validate a "complete" page if you prefer.

[AlOneill]

I've reviewed and returned this draft Help page to Refinery. It cannot be signed off as it stands — see the comments at the top and throughout the page.

I've reviewed the markup, commented on the structure, fixed some typos and made some general suggestions. There are a couple of places where I do not understand what is being said or the thought appears incomplete.

I've put the Soundex info box in its proper place — please be careful if you need to edit around it!

[PhilipClarke712]

Hi @AlOneill,

Thanks for your review, comments, and for fixing the Soundex side panel.

I was only expecting this to be an interim version of the Help page: we have a common side navigation panel for all three FreeGen sites, and not all sites appear to make use each heading on their navigation-panels. This page does use all the links, but two sections are not being "populated" in this version of the page - and are marked as such. Furthermore, some its intended sub-pages will be implemented in post-MVP version(s).

We are both in agreement there should be no pseudo-links. I thought that I had taken them all out. Sorry about that.

Note: the original version of this page did not use mark-down hyperlinks, so in some cases I had to go back to FreeBMD(1) to see what the link should be. Some such links are to pages that have been partially merged or will not be implemented for MVP. I intend to leave the pseudo-links in on a copy of this page to remind myself when working on updates to this Help page.

I will work on your comments.

Note: this page has five mark-down-style hyperlinks and some of these have their own mark-down-style hyperlinks, so you will be get more pages to look at. I had hope to do some work on these while you were reviewing this page, but I switched to the About page, and then ran out of time.

[PhilipClarke712]

Hi @AlOneill

I'm sending https://test3.freebmd.org.uk/cms/help/draft-help-1st-interim-version back to you for re-review. I beleive all the issues raised have been addressed either by reworking and/or adding new material, or by removal of text relating to functions not yet impliemented on test3. Sorry - that may involve a full review.

I'm also send https://test3.freebmd.org.uk/cms/help/draft-help-1st-interim-version which is a cut-down version of a page previously reviewed under its own story. It is one of about five or six pages referenced from Help via mark-up hyperlinks. It contains some amedments arising from issues raised in its review. This is the only page called up by mark-up hyperlinks that is "ready for review" in my oppinion.

Hi @PatReynolds

Having forwarded these two page to Alsion for re-review. I am now unavailable in respect of FreeBMD documentation unitil my return on 5th July.

[AlOneill]

@PhilipClarke712 You have passed me the same page twice, rather than two different pages. Please clarify what the second page is. Thanks.

[PhilipClarke712]

Hi @AlOneill Sorry, the second one should have been: https://test3.freebmd.org.uk/cms/help/draft-civil-registration-through-the-gro-w-in-p/draft-districts-volumes-and-pages-interim-version

The directory path is somewhat convoluted as I originally had its parent page within Transcriptions, Coverage, or Records (that name has been subject to change over the last 14 months). The directory path can be shortened if you like.

[AlOneill]

With testing due to begin soon, Pat and I have worked on restructuring the "draft Help (1st interim version)" page, re-writing it as 3 pages so that the:

• language is more friendly and the pages are more inviting to read

• information is accurate for the current layout of the form and capability of the BMD2 search (rather than for BMD1 or REG!)

• pages are not cluttered with multiple promises of help and information that is not yet ready to be published

We have spent considerable time testing various aspects and features of the search, but certainly could've got something wrong. If you believe that something has been cut in error or that something important has been missed out, please report it here — rather than edit one of the pages.

The pages to be reviewed are: https://test3.freebmd.org.uk/cms/draft-help-for-mvp https://test3.freebmd.org.uk/cms/draft-help-for-mvp/draft-more-about-searching https://test3.freebmd.org.uk/cms/draft-help-for-mvp/draft-more-about-names

I'm working on inserting the images, updating the "Detail Information" images now that the name casing has been fixed :-) — too soon, name casing not quite fixed — should be Edith Daisy DENT, for example (not Edith daisy DENT)

[PhilipClarke712]

Hi @AlOneill

You have hit the nail on the head. The page is more user friendly, I agree with that, but it started off as a straight copy and paste of the REG Help Page - including its header colours (light brown font colour ) and I suspect that page might have come from an amalgamation of several BMD1 pages. My task was not to do a wholesale rewrite and not really to add new material (but I have added new material), it was more about putting hyperlinks to BMD2 pages that did not even have markup-style hyperlinking and improving the grammar, etc.

The goal posts got moved during review: however, users will get better page(s). I don't recognise this as a REG help page: so commonality has gone, well unless REG now copy and paste these Help page(s)

I believe it was you that indicated that some people work across all three sites so commonality was a good thing: that is where the promises come from, the side navigate panels are also identical across the three sites and some links were blind links.

I don't accept that is a BMD1 help page, I spent several weeks running searches on test3, and that is what I've raised several stories on GitHub - information that is in the GRO Index was not being provided on test3. Some of which has fixed, but not all. The page I sent you describes how you might use test3 for searching and what it provides; not the way BMD1 does it.

I was intending to send more of the pages to review, these were sub- pages called up in outline mark-up, but they don't appear to be needed any more.

The one thing that I would note is that there is a story to remove the word Postem and replace it with a friendly version. BMD 2 still uses Postem, as does this page. My Postem help page, which is unfinished because there was almost nothing to search for on test3, was originally called Add a Note , but every instance was changed back to Postem, because test3 used Postem. I don't know if Add a Note is *still) the intended replacement - the story does not state what Postem is to be replaced by.

[AlOneill]

@PhilipClarke712 Yes, the pages are more user-friendly — an essential improvement now that we have the opportunity to work directly on pages such as 'Help'. A style of writing that is in line with a magazine article rather than a technical manual is what I've been trying to encourage.

Thank you for the testing that you have done. Let's not quibble about which bits of inaccurate (for BMD2 as it is currently) information are left over from where or what. The point is that, for testing and the MVP, we need accurate, current information. For instance, the description of the options in the 'Age at death' drop-down was wrong in part; and I could find no evidence that selecting 'Phonetic search on surnames' applies currently to 'Spouse surname'.

Some, if not all of the sub-pages you mention will be needed in due course. Let's see what feedback we get from testing and then adjust the timing of what we release and when.

The story about 'Postems' is still at an early stage — there will be more discussion before a decision is made. We will have to update the relevant terminology if and when that becomes necessary.

[PhilipClarke712]

@AlOneill ,

Thank you for your comments. It is interesting that we have very different view points on quite a small number of topics.

I did no testing of Age at death searches and I did no testing of Phonetic searches. I've never used phonetic searching on BMD1 (and I have been using it for research for about 16 years) neither have I attempted to do so in test3. It is good that you found and corrected errors.

Yes I agree that the latest #352 Postem story may be at an early stage. Last year the requirement was to call the dedicated "Postem" Help page "Add a Note". That was discussed in #133 last November when #165 was opened. #352 is a reminder that Postem should be replaced with something friendlier. Perhaps that change is not needed for Beta testing.

Work allocation on documentation was governed by what was specified at that time as MPV and what was not MPV. That was covered by #247, which was closed last December. I am content to slow down or stop. Apart from the need to have both the Help and the About pages ready for Beta testing (a date that is unknown to me), your comment above is the first I've heard about moderating how and when I send MVP pages to you, if that is a correct paraphrasing of your statement above.

[PhilipClarke712]

@AlOneill Sorry, I need to correct one statement, above that on reflect was wrong.

I have a family tree stored my my computer so I have relatives for which I know their dates of birth and dates of death. I did some testing using them as examples.

The GRO index did not have age at death before 1st Jan. 1866, so I tested either side of that that year, I also tried, for those limited samples, doing searches using the Match only recorded dates. I believe that the draft Help page I sent did describe what test3 could do.

I can only assume that your comments apply to the paragraph: ........ comprehensible (for example, 31JE1910) unless Match only recorded ages/DoB is specified. The search results will include the approximate dates of birth, for example if you search for 23/7/1910 you would get entries that had -JY1910 or about 1909 as the Date of Birth

I did not try and test any of those claims. Its a rather small paragraph on very large page - I would not like to view that on a smart phone, but page size was never raised during your first review of Help one month ago, as of now.

[AlOneill]

Images added to pages (edited name-casing and font of 'Page' in browser for screen-shots neither issue fixed yet).

[PhilipClarke712]

Hi @AlOneill

You may wish to re-review the section Middle names and initials within the draft Help Page More about names.

The first FIXME link is to a page Summary - use of initials in Forenames which exists in draft form and is complete in what it intends to do, but it does have a non-data data-table in it. That page has not be sent for review: it might perhaps be acceptable if the table was made say into a definition list, That would not take particularly long to do if that is the way forward.

The second FIXME should go to the, same, summary page. On BMD1 it went to the long-version of that page. This page does exist as a full width page (not 3/5 +2/5 ths), work-in-progress, and three subpages of data tables, but they are not suitable for use. I suspect from the data in the data-tables it was produced on BMD1 about 18 months ago as it starts to run out of date after 1989

[AlOneill]

@PhilipClarke712 The immediate solution for those FIXME links is either to promise that information will be available soon or to remove all mention of such information for now — it all depends on how quickly the "Summary — …" can be made ready for publication and how important it is for successful searching.

My feeling is that the Summary is highly unlikely to be ready for testing and MVP as there is a lot of work to do: the language of the page is not accessible to the general reader, the table is inappropriate (as you rightly say) and the best way to present the information is not obvious — changing the markup alone might not be enough.

Deciding between a promise for soon and removing all mention is less obvious — it boils down to the importance of the details in it to a Researcher. How often do you consult those details? Or, do you decide on how to search using forenames and initials in a different way, one determined by your experience and that could be tricky to describe? (Do treat those questions as rhetorical — only there to provoke thought!!)

So, is the Summary important enough to be a priority (the soon option) or is the advice offered on 'More about names' enough for a good while?

[PhilipClarke712]

@AlOneill

The proof is the numbers in https://www.freebmd.org.uk/givenname-initials.html but not one is going to look at that and take it all in.

Much of the text in the summary part of that page is already in Refinery in various drafts of Help, so its sort of "padding" on top of a table in a separate a summary page.

My inclination would be to drop just that summary "table" wholesale into the Middle names and initials section, say as an set of paragraphs or list; or into More about names as an annex / appendix. But, not as a table.

So this in words, possibly as a ordered list, is:

e.g Between 1837 qtr 3 and 1865 qtr the GRO index showed the forenames in full with very few truncated as (minimised to) the first initial of each name ..... but there are two anomolous quarters of ....

1910 to 1965 it's just the first full name and any initials .........

What follows in a partial capture of the table that gets converted into formatted text.

You have seen more pages that I have, but https://test3.freebmd.org.uk/cms/draft-addition is an indication of a level 4 section, that once cleaned up might be added to the end of the Middle names and initials section. I have yet to check it against the raw data in the main tables on BMD1.

[AlOneill]

If our simple advice to search on forenames, to use the first forename plus the next initial, works in pretty much all situations, then why complicate that with the Summary information on the same page?

My testing indicates that a search on say 'john f' would also find 'John Frederick', 'John Francis' and so on. Is that not sufficient here?

My feeling is that the Summary would be of interest to only some users and is not essential for a successful search. Let the Scrum decide?

[PhilipClarke712]

The quickest and least effort option is to remove those two FIXME and some text in brackets.

I don't personally read the how to search page(s), now, on BMD1 before I search.

I did at one time if, say, I found only one half of a marriage pair. Soon, I knew how to look at Coverage charts - so my first check would be "how much" of that data-set had been transcribed; and than I would be looking at UCF entries / mis-indexing / mis-transcriptions of that page number and volume number.

[AlOneill]

@PhilipClarke712 Once you have completed your checks and corrections to the Summary, let's have another look at how to present the information — I'm thinking that a diagram, a 3-stranded timeline perhaps, might be a good idea to explore (as an adjunct to any text, for users who can see).

The other topics that you mention — UCF entries, miss-indexing (or miss-transcription) of page and volume numbers — could also be candidates for updating soon. Keep thinking about what would be most useful for a Researcher.

[AlOneill]

@PatReynolds @DeniseColbert @PhilipClarke712

I'll be promoting the three DRAFT pages to 'Help', 'More about names' and 'More about searching' tomorrow, Wednesday. I'll do my best to avoid broken links and other awkwardness during the process.

The remaining three versions of the Help page (!) will remain in place temporarily (as re-named pages), pending deletion on Friday. @PhilipClarke712 if there is text on any of those pages that you need to get a copy of, please do so before Friday.

Any future changes to 'Help' must be based on the new, plain 'Help'.

[PhilipClarke712]

@AlOneill ,

1. As of yesterday's threads, I was working the basis that we would not be using the summary page as-is for beta, so it has not changed - it still has a non-compliant table.

What I did was to take a copy of the non-data table and convert it into a definition list and put it on to html page that only has a level four header (it is not a proper or full page). That is now to be found at https://test3.freebmd.org.uk/cms/help/draft-summary-use-of-initials-in-forenames/draft-replacement-text-for-non-data-table . I started making changes to the words, but I have not worked my way down the whole page, so inconsistent coverage - which you are likely to notice. It would help to know if the information in the page is to be used (see below) as I will need to finish it.

Potentially there are three or four ways forward. (1) don't make any use of the summary, in any way, for beta; (2) use the replacement text for non-data table and copy and paste it into more about searching as a level four section ; (3) make the replacement page into a proper page and use it as a sub-page of more about searching ; (4) over-write the table in the summary page with the replacement text and use that page as a sub-page of presumably more about searching . I'm tending to discount option four as there is a lot of duplication between more about searching and the summary page.

So, I need to know what the decision is, because I might need to finish it and to either copy it or possibly make a full page.

2. I will take an off-line copy of the Help (1st interim version) because that will have the scope of what I anticipated would be in the Help page, together with a the mark-up hyperlinks. Obviously the means by which the information is communicated has changed.

3. This is going a bit off topic, but there is another story for https://test3.freebmd.org.uk/cms/help/draft-reporting-errors-in-transcriptions and that has two mark up hyperlinks that are not ready (reviewed). One to a Postem page that is not ready (so I might just remove the reference) and to Help with Marriages. That page was not ready for signing off earlier this year because pages hyperlinked to it were not ready. It does not look anything like the new Help page - but we could copy sections out of it. There is now a lot of common ground between Help and Help with Marriages. If we use Help with Marriages it will need to be decluttered.

[richpomfret]

Should now be pushed into test3. User testing can then dictate what changes come next.