Page 1 of 1

The Knowledge Base

Posted: 15 Jan 2020 15:38
by ColinMc
In Template codes (17370) I was given a link to Knowledge Base > Narrative Report Fact Sentence Templates page in the KB.

I must admit while I knew of the KB, I did not think it was as good as it was. I've used the "Getting the Most From" booklet as a main reference, but I think I'll look at the KB in the future. I've printed off the index to keep as a desktop reference guide.

Could I however, make a request as a constructive comment though. I do appreciate the effort and the time that has gone into it, The Content seems great, but its readability is hard. I would like to suggest not immediate changes, but that when pages are re-written or updated, that some different thought is given to how they look to the user.

For me, there is just too much colour, bold and hyperlinks. It is very distracting when reading, making it difficult to take in the meaning as the eye is constantly drawn to the highlighted text.

If I did click on every hyperlink to read the link (I think there are 14 just in the view below alone) then firstly I'd never finish the original document, and secondly I'd probably have lost my place anyway, and never get back to the page I started at.

help.jpg (397.28 KiB) Viewed 1845 times

Towards the end of that page, it turns into almost total bold text - making it hard to read

help 3.jpg
help 3.jpg (152.87 KiB) Viewed 1845 times

Key differentiating words here such as Sentence and Template are semi-obscured by the black, and almost disappear from view.

The most important part of the KB should be the index, but its is in the smallest font, and contains too much duplication. Much of the Grey/Black text is an exact, or similar repetition of the Orange hyperlink, If there is only the one topic, then both descriptions might not be necessary in some cases.

It may even be that the "Knowledge Base Titles" page is of more use than the Index. Are both actually needed?

help 2.jpg
help 2.jpg (279.94 KiB) Viewed 1845 times
Apologies for going on a bit. As a Resource it is great, and fills a lot of blanks from the Official documentation, but it could be easier to read.

Re: The Knowledge Base

Posted: 15 Jan 2020 16:44
by tatewise
Colin, I've moved this to the Web Site Usage forum that is more appropriate.
Thank you for the feedback, as we get very little usually.
Some of the points you raise we are aware of.

I presume you realise that the Knowledge Base is a wiki just like Wikipedia that has similar 'distracting' blue hyperlinks ~ you are not expected to follow them all ~ they provide cross-references for terms you may be unfamiliar with.

I have never been in favour of the orange coloured hyperlinks. As you say, when bold they are too strong, but without bold they are too pale. I would prefer the traditional blue hyperlinks.

Bold black has been used quite often to identify literal codes, but when they are long they do become overwhelming.
Elsewhere we have started to use a grey background style like that shown in Knowledge Base > Text Formats for %INDI.BIRT.DATE%

Many users find it difficult to find advice about whatever topic they happen to be searching for.
The Search box top right only works if your keywords match the Knowledge Base keywords.
Similarly, the Knowledge Base > Knowledge Base Titles don't help much unless your keywords are in the title. The Titles are not in any logical grouping but purely alphabetical, which users found unhelpful.
The Knowledge Base > Knowledge Base Index is a new idea that is still evolving and meant to be more like a reference book index, where the same topic is listed under various related Subject headings and organised into related groupings. The style of the text is largely dictated by the wiki. I disagree that the black topic text and the orange hyperlink are usually the same.

We have recently been through a major exercise with the Knowledge Base > Contribute Your Knowledge section to make it more approachable and logically structured. BTW: You can use that guide to change any of the Knowledge Base as you deem fit.
Most of the other sections are smaller and better structured.
BUT the Knowledge Base > Family Historian section has a chequered history and grown like topsy as FH has gained more and more features, many of which are not covered in any depth in the FH Help pages or Getting the Most From Family Historian. It is long overdue for a major overhaul too! BUT that is an unenviable task.

Re: The Knowledge Base

Posted: 15 Jan 2020 18:28
by ColinMc
I was not aware that the style was effectively forced on to you. That does make a difference

I will have a look in more detail at the Contribute your own knowledge section to see if I can learn more there.

However, the Index is still a little more complex than it needs be
Understanding Data References Understanding Data References
Understanding Expressions Understanding Expressions
Understanding Functions Understanding Functions
Is one example where it is un-necessarily complex.

Does anyone else have thoughts on this?

Re: The Knowledge Base

Posted: 15 Jan 2020 19:08
by tatewise
A lot of the features in the wiki are derived from built-in options and predefine installed macros.

You have picked out three unfortunate examples in the Index that might be better.
However, the point is that they are grouped logically under Customisation and could just as easily appear as:
What are Expressions? Understanding Expressions | Understanding Data References | Understanding Functions
or any other subheading you would like to suggest, but still grouped with Customisation rather than say Fact Types.
Note that those same topics also appear under Data References and Expressions and Functions.
So whether a user starts from the keyword Customisation or Data References or Expressions or Functions they should reach those Understanding... topics.

Whereas in Knowledge Base Titles they are lumped in with every Title starting with U such as:
Uncategorised Data Fields
Understanding Data References
Understanding Expressions
Understanding Functions
Understanding Lua Patterns
Understanding Projects
: : : : : : : : : : : : : : : : : : : : : : : : :
Useful Research Software
Useful Research Web Sites
: : : : : : : : : : : : : : : : : : : : : : : : :
Using Named Lists

Re: The Knowledge Base

Posted: 16 Jan 2020 12:09
by Jane
ColinMc wrote:
15 Jan 2020 18:28
I was not aware that the style was effectively forced on to you. That does make a difference
I have changed the knowledge base links to DarkBlue and turned off the bold.

The bold on the other items are entirely in the control of the editor of the page.

Re: The Knowledge Base

Posted: 16 Jan 2020 12:19
by Jane
For the example with the templates and the Sentences you could use unordered lists eg

Code: Select all

==== Census Event ====

This style caters for the **1939 National Register** and relies on the full address being in the **Place** field.

  * Template: 
    * {individual} appeared in the {=TextIf(GetDisplayText(%FACT.DATE%,min) = "29 September 1939","National Register","Census")} {date} residing at {_place} {age}
  * Sentence:
    * He appeared in the Census on 31 March 1901 residing at 48, Springfield, Oxford, England aged 48.
    * He appeared in the National Register on 29 September 1939 residing at 5, High Rd, Oxford, England.

Similarly for the **Census (family) Event**:

   * Template:
     * {couple} appeared in the {=TextIf(GetDisplayText(%FACT.DATE%,min) = "29 September 1939","National Register","Census")} {date} residing at {_place} {their ages}
  * Sentence:
    *  They appeared in the Census on 31 March 1901 residing at 48, Springfield, Oxford, England when he was 34 and she was 31.
2020-01-16_121750.jpg (131.71 KiB) Viewed 1729 times