Add "Help with Citations" to Help for Researchers

[PatReynolds]

Text added to a draft page (under About) in test3 .

Decision needed on whether to make it part of the main About page, or a sub-page.

[PatReynolds]

Draft text added to the Help page. Will need: -[ ] link to the section of About page or sub-page rather than the current link (just to the About page -[ ] Caution on use during the testing Phase of FreeBMD2 (i.e. that the link is to the url currently occupied by FreeBMD1).

[PatReynolds]

@ComfE-2662 could the Development team review please

[richpomfret]

@ComfE-2662 any update on this in terms of it being tested?

[DeniseColbert]

@PatReynolds could you clarify specifics of this story for Taylor please?

[PatReynolds]

@taylorjgolden could you look at the help for researchers page on test3 and check that it includes a section on citations - check using the Checklist A and Checklist B in the Protocol for creating and editing in Refinery - please let me know if you have difficulty accessing the documents, or need something more specific. With thanks, Pat

[PhilipClarke712]

I would note that there are two such draft pages, quite different in their level of detail. On Test3, they are About Citations and Citing FreeBMD, respectively. They don't comply with those Checklists in one aspect at least: hyperlinks exist and are working, because the Checklists are incompatible with the Protocol for creating and editing in Refinery:- the latter has Don't hyperlink to draft pages.

The more I work with Help the less I like it. Reading the text, it comes across quite well (but Test2 has a note stating that it was copied mostly from FreeReg). But: a lot of it was copied from other sub-pages, resulting in three-levels of duplication; and there are/were level-three headers that include CSS to make them look like level-two headers. I would suggest that it is far easier to change h3 and /h3 tags to h2 and /h2 tags than to add css.

[PatReynolds]

@PhilipClarke712 yes, there is information about citations (in detail) in About, but what someone needs to know to use the buttons on the website.

Headings should always be tags, although the styling will be in the CSS (and we do not need to deal with that).

I will go through Help and make sub-pages for those elements that I think are too wordy to be here,.

[PhilipClarke712]

@PatReynolds Sorry, I did a bad job of explaining what I meant. I should have said that the CSS was being over-ridden by adding font sizes and other means of changing the text appearance into some of the tags make level 3 tags look like level 2 tags. It's far easier to change an h3 to an h2 at both ends of the paragraph.

We have perfectly good subpages on Refinery, sitting under Help: "Age at death", "how best to search" and "searching", etc. The page seems to be put together by taking it wanted out of existing subpages, but making no reference to them and missing out the things that FreeReg does not use. There is no reference to Postems, nor ordering certificates, nor help with marriages, nor Late Entries, nor Advanced search facilities: perhaps because FreeReg does not use them. So these things are on the FreeBMD(1) but not on FreeBMD2 because they were left out.

Comfort had done quite a passable How best to Search page, which was missing a side navigation panel, but that page could have been expanded to create a Help page which would included most of the FreeBMD-related help material.

[PatReynolds]

Thanks, Philip, we have almost finished the standards page (wish we had started that in 2018 .....) and the next thing @DeniseColbert and I are going to work on is the document on how to bring html text from FreeBMD1 to FreeBMD2 so hopefully in future it will come over clean.

I think it would be great to use Comfort's page as the basis for Help for Researchers (different Help will appear for logged-in volunteers, once more functions for them are reached via FreeBMD2 - but that is far in the future, and may only be a small amount of things, eg things currently on on FreeBMD1).

[PhilipClarke712]

So you are the Latin expert. I saw it earlier today and assumed that Alison had done that. Note: I did Latin and (Castellano) Spanish at night school about 8 to 10 years ago: same teacher, but she was a Basque. I was better at Latin than Spanish, but with that mixture I could understand about half of what Inspector Montalbano said (a Sicilian detective series that was on BBC4 on Saturday nights a few years ago - it ran for about two or three years). Yes, I ran out of work for a few months in the Summer, if the standard (or at least the need to use active-verbs) had been available then it would have taken off some of the time pressure that has arisen now.

[DeniseColbert]

Protocol for editing and creating in refinery: https://docs.google.com/document/d/1hox-YaO3YctWDTzr9yr30jdyPwZ30lyNZb4qnZs5Xf4/edit?usp=sharing

[richpomfret]

@taylorjgolden @DeniseColbert any update on this story?

[DeniseColbert]

This looks to have moved on a bit since I was assigned, it's not clear what needs doing.

[PhilipClarke712]

I would note that this topic of citations is covered twice from different viewpoints: (1) the detail of citing FreeBMD in e.g. Harvard, Chicago, or MLA "house-style" appears on the About page https://test3.freebmd.org.uk/cms/about ; and (2) a statement of FreeBMD auto-generated citations appears on the Help page https://test3.freebmd.org.uk/cms/help#cite and this section has a link to the section in the About page (but not the other way round).

Those two pages are likely to go unchanged onto Beta (well unless there is a strong desire to change them - that would mean getting any changes "signed off"). These two pages are not draft pages, so they appear to have been signed off.

So, is there a desire for change / improvement to what is on those two pages?

There is no example of a real citation: I got this one from a search on FreeBMD(1)

I just tried test3 and I've not found any citations (Note: there does not appear to be a means of viewing an image, which was there last time I used it). I'm not sure where citations would / should appear on test3; and / or what they look like.

[AlOneill]

@PhilipClarke712 @DeniseColbert These pages have not been signed off for HTML — even a cursory look at both "Help" and "About" shows issues including bad syntax, links to non-existent pages and to one very out-of-date page (the "News" page has nothing later than 2015!), non-standard formatting of sub-menus and typographical errors.

If the content is complete then I suggest we stop treating them as draft pages, do a full check of the HTML and any other issues, and then make any further edits using copies as properly-named draft pages, as per our protocol.

Is it too soon to treat them as content-complete? How do we want to proceed?

[PhilipClarke712]

Hi @AlOneill @DeniseColbert

Sorry, I can't comment on whether they are signed off or not: I did not write either of them so I was not involved in their production. However they do not have the prefix Draft in their names. So by definition they are not draft pages and that means that I can't work on them, only on copies that I make of them. Note: "splitting hairs" I can't (I think) work on live pages -those are live pages, because people can view them without being signed on in Refinery.

In respect of the Help page I would refer to issue #173 where back in January of this year Pat requested that I switch the order of the first two sections. From memory there was off-topic correspondence between me and Alison, and the advice was that I could only make the changes to a copy so that is why there is a draft DRAFT - Help (edited original) - DRAFT and that is what I stated on #173 at that time. Note: There is also another draft DRAFT Help (W-i-P) , which predates the other draft and to which I was intending to make significant changes, but never got to it.

So far I've tended to stay away from these top level pages and work on individual pages within Help and Coverage.

Now given a "freehand", which I don't have, I would rewrite the Help page to add in-page hyperlinks and a side menu. The side menu would link to the (what are at the moment, draft individual pages) Late Entries, Help with Marriages, Postems and Frequently Asked Questions (Researchers) because there is a need (and a story raised by other people who want them). That would be only the first set of changes. I can't do Help and About at the same time, so I need to choose one: Help is the biggest one, so that might indicate that I should re-think the order.

The current Help page appears to have been made by (this is rather an unkind comment) by copy and paste from other help pages either on test3 or FreeBMD(1), for example from Age at Death, etc so draft pages like this are semi-redundant (or in limbo) as much of their content is also now on the Help page. However, this Help page does have the advantage of being comparable with FreeREG and FreeCEN (and currently almost no hyperlinks to other test3 pages).

The current About page includes some of the About FAQs, but not all of them; and as stated above is out of date. So there are three stand-alone FAQ pages that we need to include somehow into About and Help, without over-repeating ourselves. Doing that is not a trivial task (particularly as many FAQs reflect FreeBMD(1) practice and so may not be relevant, or in need of re-write).

The biggest problem (in my view) is the signing off process, which I think probably works well on a stable / mature system, but test3 is not stable and not mature. Alison reviewed, my draft Help with Marriages page back in February and greatly improved it. But: it can't be signed off until all the hyperlinked pages and subpages are sign off (I think at the top level that is only another two pages), One of these is another draft page Ordering Certificates which has also been reviewed, but can't be signed off for the same reason (and some of its links are to a FAQ page which has a large number of outline-hyperlinks links to other pages as well as to District pages, some of which need to be done by D&T.

So, if I were to make, say, just a simple change to one of my copies of say the Help page, just adding a side menu to Help with a reference to Marriages and Ordering Certificates sub-pages, none of those pages (assuming they are fit for purpose) can be be sign off until every page hyperlinked or referenced within them are also signed off. That is a very large incentive not to change anything using a top-down approach (bottom-up is what I have been doing, which is why these two pages are untouched).

Sorry for the long rant:

My proposal would be to produced another draft of the Help page (using one of its two current working drafts), put out-line hyperlinks in it and a side menu so that I can link into Help with Marriages, Late Entries, Postems, Citations (some of which will be on Help and some on About).

I may need to link to a new version of How best to Search (after removing duplication between it and the Help page. At a later date other things might need to be added.

There are problems, some of the things to be described are not yet implemented on test3 (but being worked on by others, especially Vino-S ) and some of the hyperlinks will only be in outline form to draft pages (either not finished, or reviewed by awaiting other pages to be signed off, etc).

Doing all of these, reviewing them and signing them off, appears to be another large Brexit-type process (fortunately without the European Commission and 27 other nations) but - slow, very slow.

[PhilipClarke712]

Hi @AlOneill , @DeniseColbert

It is my intention: (1) to submit fairly soon (days, not not hours) a reworked draft of the Help page (it will not have any new info added to what is there now). That can be covered by other stories. (2) look at the https://test3.freebmd.org.uk/cms/help/draft-citing-freebmd with a view to getting it signed off

"About" is a live page and in respect of this story it has the majority of the citation information. Some of About's defects, mentioned above, can be fixed by editing a new draft copy, but some of its hyperlinks are to, e.g. FreeBMD(1) pages, FAQ's and the Coverage charts in particular, that are either not anywhere near to being sign off, or non-existent, on test3. So, it might have to be updated in several stages, e.g. signed off more than once; and there are other stories covering this.

Note: Providing more up-to-day news is not an intrinsic part of help with citations (that issue has it's own story #306 ) and it's a live sub-page of "About" called from the side menu, so it's really outside this story. [I can't comment on whether the History sub-page is signed off, I don't have access to that information.]

[DeniseColbert]

We think this is now complete but will check

[PhilipClarke712]

Hi @DeniseColbert ,

This dropped into my in box, because I'm on the list.

I'm not giving to give you a yes or no answer, sorry about that. Jump to the final paragraph it you want the quick answer.

I think at some point my fingers and brain got disconnected; there is no https://test3.freebmd.org.uk/cms/help/draft-citing-freebmd . I think it should have been Help with marriages - but that help sub-page is no longer called up by the MVP Help page - so ignore that comment particular comment of mine above.

I'm think I am correct in saying that the only reference to Citations is now to be the found on its own section on the About page and that is quite detailed from an academic viewpoint, but probably not for a researcher. It talks about auto-generation (see later) which I suspect is not running on test3.

FreeBMD1 and the various test3 draft Help pages did have a Citations section which was concerned with the citations you could get (on BMD1) using a "permanent" (if that is the right term) URL - which I believe in not yet functional on test3.

My draft Interim Help did have a Help section and a hyperlink to the citations section on the About page. After it recent review and rewrite, that become three pages, the top on being Draft Help (for MVP) . This main page no longer has a Citations section, and it looks like the two sub-pages don't.

So, the main question becomes is the Citations section in the About page all that is needed? If it is thought that the Help (for MVP) page needs to cover the topic as well, then someone else will need to put it in ('ve been asked not to work on it, but requests can be left on its Story page #173 ).

[AlOneill]

Citations are covered in the DRAFT Help (soon to be plain Help) at: https://test3.freebmd.org.uk/cms/draft-help-for-mvp#share

This part of Help will need to be updated when the automatic citations feature and button are implemented.

There is a link, in that same part of Help, to the section of About that (currently) covers the citing of FreeBMD. It is not quite accurate as things stand, because it states that automatic citations are available. It will be corrected ASAP.

[PatReynolds]

@AlOneill to check

[AlOneill]

Page has been updated re citations button not being available yet.