Family Historian User Group

In Help resources in TMG and fh (15685) Mike Tate said:

I accept that the FH Book does not list Citation in the Index but it does have Source Citation. However, I agree its Index has room for improvement.

This reminds me that I have often thought the same about the “index” in the Knowledge Base. I know most people probably use the search box in the KB rather than the index, but a new user might head for the index, particularly if they are used to a traditional printed index.

It does have an entry for Citations but that is almost by luck. The so-called index in the KB is in fact just a list of Contents sorted alphabetically. There is a difference. Each entry in the KB “index” is just the title of a section in the KB, which in many cases doesn’t start with a word you might be looking for. That’s not an index.

Example 1: Suppose a new user has a question about printing large diagrams from a PDF. They won’t find what they want under P for Printing (the most obvious place to look), or P for PDF, or D for Diagrams or C for Charts or L for Large. It’s under S for Single Page PDF of a Diagram, because that is the title of the section in the KB.

Example 2: Suppose a user is having problems installing or upgrading. They won’t find anything under I for Installing or U for Upgrading. It’s under F for Family Historian Installation Advice/Details/Problems!!

I’m not sure what the solution is. It’s tempting to suggest removing the index completely, because it’s not a proper index.

[kb]|[/kb] Index criticism accepted, although it has been that way for more years than I care to remember.
It conforms to the usual concept of a Wiki Index of article titles, which is different to a Book Index.

Actually, there is an Alphabetic Index in every main section, but perhaps better renamed to an Alphabetic Contents.
The introduction to each one could refer the user to the Search feature to find key words.
Those changes would be relatively quick and simple to implement.

However, I think building a Book Index would be an extensive exercise, but may be a project worth starting?

I'd agree there - I always automatically go for "Index" first and get frustrated because the entry isn't there. Then I try "Search".

I never go for "Search" first because I reckon that I'll get every reference to that word and if it's a common word.... It's actually never occurred to me that "Index" had a basis, I always thought it was simply a poor (Book) Index!

BTW: Over the years I have spent some time re-organising the article titles so they are more co-ordinated in the KB Index lists.
You should have seen what it was like before I started that exercise, because the article titles had given no thought to how they appeared in the KB Index lists.

For example, Single Page PDF Printing of Diagram could be changed to say Printing PDF Single Page Diagram.

It is also possible to create a dummy article, that quickly switches to the root article, just to get an entry in the KB Index.
As an example, I've created a dummy article for how_to:printing_pdf_single_page_diagram|> Printing PDF Single Page Diagram that appears in the Index and switches to how_to:creating_a_single_page_pdf_of_a_diagram|> Single Page PDF of a Diagram. So whenever anyone wants to add an Index entry, that can be done very easily, and several dummy articles can all switch to one root article.

One way a Book style Index could be built is to use the technique employed in the glossary:animated_tutorials|> Animated Tutorials page, where the list of alphabetically sorted pages is compiled automatically from pages that contain the tag Animated-Tutorial.

So the Index would list pages synonymous with the tags, and each such page would list all pages containing that tag.
Thus a cross-reference Index of keyword tags would exist similar to a Book Index but with page links rather than page numbers.

It might be a good idea to bring the Changes, FAQs, Index entry to the top of each main section, such as I have done in ancestralsources:index|> Ancestral Sources for example.

As an example, I've created a dummy article ...

Yes, that system works well.

In the other example I gave, where an article about Installation problems can only be found under F for Family Historian, would it be simpler just to delete the words "Family Historian" from the title of a lot of articles? The words are redundant in the context of a website about Family Historian. Or do the words need to be there for purposes of searches from outside the site?

As for the best way of creating a book-style index, I'm happy to leave that to your judgement.

But the FHUG website is not just about Family Historian but also Ancestral Sources and maybe other components that need installing.

It also can become inconsistent when you consider pages such as Family Historian V5 & V6 Migration Guide versus Ancestral Sources Migration Guide.

OK, understood.

BTW, when choosing a title for a 'dummy' article a good strategy would be to think about how new(ish) users would phrase the question. For example a typical question is 'How can I print a large tree/chart?' They might not know that it can be saved as a PDF file and they might think 'Single Page' refers to a single page from a multi-page chart, or a small chart that fits on an A4 page rather than a large sheet.

The emphasis is on the fact that they want to print something large, so instead of Printing PDF Single Page Diagram perhaps a more general title like Printing Large Charts would be better?

See my experimental alphabetic_index|> Knowledge Base Index that offers a Book Index but only one level of keywords in one column, unlike the Plugin below that offers a multi-level standard style Book Index in multiple columns.

I've found a DokuWiki Plugin at https://www.dokuwiki.org/plugin:subjectindex that automatically compiles a Book Index from entry tags inserted in the wiki pages, but Jane would have to install it before we could experiment.
e.g.
If one page is tagged with {{entry>books/fiction/writing novels;-}} and another with {{entry>books/non-fiction/writing facts;-}} then a Book Index entry is compiled as:

• B
  • books
    • fiction
      • writing novels: page link
    • non-fiction
      • writing facts: page link

I have installed that plugin for you

Thanks for the time you are spending on this Mike. The examples you have created are all a great improvement on a simple alphabetical list of titles. I think it's already clear that whichever scheme you decide to use, it will be a great help to people who are used to a traditional style of index.

Thanks Jane, I've added {{entry>...}} tags, and the alphabetic_index|> Knowledge Base Index has the {{subjectindex>section=0;cols=2;title;default}} tag, but says the The Subject Index is empty! so I guess the Wiki needs to be refreshed (again) to build the Subject Index.

However, the Wiki Plugin is definitely working, because the {{entry>...}} tags are recognised, and when clicked they correctly jump to the alphabetic_index|> Knowledge Base Index page.

If we can get this working, then all we need to do is think up the appropriate Index keywords and add all the {{entry>...}} tags. Note that these tags can be added anywhere on a page, and I hope the link from the Index will land on the Heading just above the tag, but even if not the presence of the tag can identify where the relevant details exist, or it can be invisible.

Jane, it looks like the Wiki has partially refreshed, because both the old {{tag> Index-Property-Box }} and the new {{entry>Property Box/Dialogue}} style tags have updated correctly, but all the Printing and Workspace tags, both old and new, are now missing, and many Backlinks are also missing!

I have confirmed that placement of the {{entry>...}} tags is important in determining where the Index link opens the target page.

The index rebuild stopped part way through. It takes half an hour so I can't watch it. I ran it again late last night and seemed to go through OK

Yes, thanks Jane, that has worked fine, and this DokuWiki Subject Index Plugin looks like the best method to employ.
So I have moved alphabetic_index#subject_index_style|> Subject Index Style to the top of the page
It has several neat features that we can exploit.
e.g.

1. When you hover on the orange links to the Wiki, it shows a popup tooltip abstract of the target page text.
   So by adjusting the text at the start of each wiki page, we can control what appears in that popup abstract.
2. When you click on the orange links to the Wiki, it opens the target page at the point where the index entry tag is inserted.
   (Possible Bug: When manual sorting of headings is employed, it always opens at the head of the target page.)
3. As illustrated, we can have multiple indented sub-headings under each subject heading.
   The same sub-heading can link to multiple Wiki pages, and the quantity of pages is shown against the sub-heading.
4. On the target page the index entry tag can appear in various forms.
   It can be completely hidden (Possible Bug: 2. above does not appear to work and opens at head of page.)
   It can be just an asterisk * inserted amongst text to show where the relevant topic exists.
   It can be any text, and an example is shown on the target pages for the current experiment.
   It can effectively be a repeat of the subject index heading & sub-headings.
5. When you click on the target page index entry text, it returns to the master Index page near its associated heading.
   (Possible Bug: When manual sorting of headings is employed, it always opens at the head of the master page.)

Looks good to me. For the bugs you could try contacting the author of the plugin, if they can not be worked around.

Remind me if you need the index rebuilt.

Unless anyone has any objections, I plan to remove the other Index Styles A/B/C and remove their associated tags.

Now all we need is a comprehensive list of Index headings & sub-headings with which to populate the [kb]|[/kb]. Any suggestions are welcome. As they are added, the Index can be rebuilt from time to time by Jane.

Has anyone other ideas on improving the style of either the Index itself, or the way the entry tags appear in the pages?

I have reported the bugs to the author via https://github.com/MrBertie/subjectindex/issues.

Mike

I prefer the layout at the top of the page that you link to in this post for the Knowledgebase. If that isn't feasible then option C.

Colin, just to be certain, do you mean the Subject Index Style using the DokuWiki Plugin?
I only ask as I've recently moved that one to the top, whereas before it was at the bottom after Index Style C.

Mike,

Just my personal taste, but I am not enamored with the DocuWiki style index at the top. I think it is too busy. For example, the topic Customise or Print Records Window Columns is listed four times in the example and it is preceded sometimes by Named Lists which is not really what it is about.

I prefer what is now option C.

Bill, maybe you have misunderstood the Index structure that is based on a technical book index style.

The first two Customise or Print Records Window Columns entries are under the main heading Printing.
That [kb]|[/kb] page does indeed explain printing both Named Lists and the Records Window.
BTW: Namd Lists are an integral feature of the Records Window.

The other two entries are under the main heading Workspace and sub-heading Records Window.
If you follow the links they actual land in two different places in that target page.
The first at the top in Introduction and the second in the Configure Columns customisation.

Also, if you hover on any link, you get a preview of what that page is about.
If you follow the link then on target page there is a link to click and return to the original place in the Index.

The Index Style C has none of those features, and needs much more manual coding.
Also in the example, it only has about half the index topics and links as the Subject Index Style.
So if it were made equivalent, it would be much larger, and yet less focussed.

I understand what you are saying, but I still think that it is too busy and confusing. Again, that is just my opinion and others may and probably do have a different opinion about it.

I think it would be better to have the topic called Customise or Print Records Window Columns as the only verbage on the line rather than Named Lists Customise or Print Records Window Columns so that it is easier to find. If I'm trying to find a topic on printing record window columns, I think having it say Named Lists at the beginning is more confusing than helpful. And I'm not sure that having a topic listed four times in the index is really helpful.

Any chance of keeping the current index along with the new index if this one is chosen? I've never really had problems with the current one.

Yes, we will keep the old style index, which is not a conventional index, but a list of all the wiki page Titles.
It is there now as knowledge_base_titles|> Knowledge Base Titles and is what Wiki often seem to call an Index.
BTW: We can control the order of topic headings, which defaults to alphabetic, but there is an override mechanism, that you can see in force under Workspace where the various windows are not in alphabetic order. So it would be feasible to put Named Lists after Records Window if we wish.

It seems that many new FH users find that list of Titles unhelpful, and want a conventional Index of topics.
So, just as a book index may have many topics that all refer to the same page number, then this Index has many topics that all refer to the same page Title.

tatewise wrote:Colin, just to be certain, do you mean the Subject Index Style using the DokuWiki Plugin?
I only ask as I've recently moved that one to the top, whereas before it was at the bottom after Index Style C.

Yes that is right Mike. I like the cascading index of the plugin plus the tootip popup. I think that it would be most useful to new users and us older hands searching for something specific.

Sounds good. Thanks Mike.