* Improving Accessibility of Commonly Requested Help

[davidf]

David, your suggestions are closer to what I had expected would be proposed.

The main challenge Helen & I faced with Contribute Your Knowledge was its top level structure.
It was organised into Beginners, Intermediate, Advanced and Technical Reference sections.
Now it is Task & Feature oriented with sections progressing through features from basic to complex. Go take a look.
Very little of the underlying technical advice needed rewriting, but simply reorganising.
...

OK I have tried and I'm afraid it feels as if my head is stuffed with cotton wool!

Contribute Your Knowledge is an interesting bit of the knowledgebase because

1. It is just about stand alone
2. It has undergone recent maintenance
3. It is about an area which I can approach as a relative naive user

It is not immediately obvious that "Contribute your knowledge" is about directly editing a bit of the FHUG website called the Knowledgebase and is about knowledge of FH (and allied fields). It is possible that some arriving here are thinking of knowledge of genealogy!

We may want to direct some "keen contributors" to responding to mailing list or forum posts before we introduce them to namespaces. I don't think we can exclude people not being over sure of the difference between the Forum and the Knowledgebase - it's all on the same domain after all!

What is a new editor of the wiki actually likely to want to do?

1. Correct an annoying typo
2. Add a sentence of further explanation
3. Add a paragraph (or a page-section?) of clarification
4. Add a new detail page
5. Add a whole new "section" to the wiki
6. Completely restructure and rewrite the whole thing (they read the whole internet last week-end, so this week-end let's do the knowledgebase! Let us hope not!)

Some of the above (1 to 3?) do not require much knowledge and being able to quickly do them, gives a sense of satisfaction and gets more people started on contributing to the knowledgebase.

So for the first 3 points above what do you need?

• To sign up and log in
• To know that you edit page-section by page-section and that inserting a new heading creates a new page-section when you save. [it seems that the "Edit this page" facility shown in the - rather old - animated tutorial no longer exists]
• That the tool bar works much like the forum tool bar in controlling text format
• Like the forum, you see the resulting formatting codes, but before committing your changes you do need to Preview them to check the impact on the page you are editing, after which you can edit further, Save (i.e. publish) your changes, or Cancel to abandon and leave things as they were.
• There is a Playground page in which you can experiment before editing a published page.
• Reassurance that if you really mess up, you can contact someone who can roll it back to as it was before you started. [Is this how you "restore" the Playground?]
• If you want to do anything more substantial you need to know a bit more, so read on..

Is a page of a few paragraphs explaining the above sufficient for a first page?

From trying to get my mind around accessing just the top of the Contribute Your Knowledge Section I become aware of a number of style issues.

• Pages are very long
• Pages have lots of links
• To get a complete "chunk of knowledge" (say to do your first edit), you have to jump through multiple links and visit multiple pages. One chunk of knowledge - one page? (Even if that leads to some duplication?)
• A screen shot or two is far more reassuring than a block of "further links"

I might have had a go at writing a new page - but so far am a bit nervous about how best to do it! There "appears" to be so much more I have to know before I even start!

[ColeValleyGirl]

If we are agreeing on the Technical Manual and User Guide Approach

Yep, but no... Depends on the platform we have to work with.

And yes, 'Contributing your knowledge' only helps the dedicated.

[tatewise]

David,
Thank you for your feedback, especially as a relative naive user, which we cannot be.
Those first impressions are something we cannot recreate.

Contribute Your Knowledge specifically says it relates to the Knowledge Base in each of its first three paragraphs.
Can you suggest how it could make that point clearer. It is an important concept.

As has been said before, the Knowledge Base is mainly focussed on FH, but there are other topics that users are welcome to contribute to, including AS, user web sites, and also genealogy tips.

We thought we had covered your bullet list of So for the first 3 points above what do you need? quite well early on.
The points are covered in the sections down to Edit Existing Pages and repeated in its Introduction.
However, we have failed if it appears to you that inserting a new heading creates a new page-section.
To create a new page-section requires an new hyperlink which is not covered until Edit Links and Media.

I don't know how to keep pages short and avoid links. They seem to be contradictory objectives.
The smaller the pages then the number of links to reach those pages will increase.
Our style is very similar to most Wikipedia pages that I have visited, that are long with many links.
Screenshots would certainly help in some cases.

[davidf]

...
Contribute Your Knowledge specifically says it relates to the Knowledge Base in each of its first three paragraphs.
Can you suggest how it could make that point clearer. It is an important concept.

But how is the first-time or novice user to know that the Knowledge Base is something specific and not just a term to cover all the knowledge on this domain - or that there are other options of which they may not be aware?

I have tried inserting a page-section to make this clear and direct users to the Forum or Mailing List if they decide that is what they want to do.

...
We thought we had covered your bullet list of So for the first 3 points above what do you need? quite well early on.

Much of this is about using a style that is novice friendly but expert compatible. We all start as novices so that has to be how the initial access starts.
The points are covered in the sections down to Edit Existing Pages and repeated in its Introduction.

But it is below the fold and for novices to wikis it may not be clear that you can make minor changes and you do not need an IT diploma to do so?

Before I put another page-section in (above the fold!), looking at the page on my laptop (15.6" screen) I would read the introduction which mentions "There are very simple ways to get started, or techniques ..." and then gives me a set of links that looks like administrative detail (hidden away behind links, but are novice users interested?) before starting with Basic Concepts that gets to something about TRACE::

I have now clicked on "About Contribute Your Knowledge" - expecting it to be like the "About" option on most applications' help menu.

What I expect when I click on "About"

About Firefox.png (71.25 KiB) Viewed 11837 times

But no! It takes me to another set of links, one of which "Edit Existing Pages" may take a novice user straight to what they want (well via a few clicks - and avoiding those "Basic Concepts" and the need to signup)!

However, we have failed if it appears to you that inserting a new heading creates a new page-section.
To create a new page-section requires an new hyperlink which is not covered until Edit Links and Media.

Well there is another concept! What do you call the sections of a page that each have their own Edit Button? I did not directly follow HTML/XTHML practice of saying "section" because I view wiki pages as being loosely grouped into sections!

I don't know how to keep pages short and avoid links. They seem to be contradictory objectives.
The smaller the pages then the number of links to reach those pages will increase.
Our style is very similar to most Wikipedia pages that I have visited, that are long with many links.
Screenshots would certainly help in some cases.

Well possibly Helen is right to be considering if we should be using wiki software?

Long link rich pages where you have to navigate through several links to get to what you want is discouraging to novices and gives them too many opportunities to go astray!

I was once given the challenge of rewriting a call centre's help system (in Lotus Notes!), so that all significant information was no more than two clicks away! It forced us to do two things:

• Think very rigorously about what information is significant to users
• Provide different Landing/Start pages determined by the user's role (from their sign-on)

It meant most pages gave a whole (but succinct) chunk of knowledge, with links at the end to more detailed information. Early in the page we gave a link for "experts" which would either take them off page or to the links at the end.

[brianlummis]

Contribute Your Knowledge specifically says it relates to the Knowledge Base in each of its first three paragraphs.
Can you suggest how it could make that point clearer. It is an important concept.

To me it is just a slight change - how about Contributing to the FHUG Knowledge Base

[tatewise]

Brian, yes we could use something like that, but it is tidier if the Title fits in the main sidebar top left.
But if that sidebar entry is a logical contraction of the Title then that could also work.
The important point is that joint ideas such as yours and David's should yield a significant improvement.

Similarly, collaborators and reviewers could make a significant improvement to the rest of the Knowledge Base

[brianlummis]

Mike, that gives a good instance as to how to fall at the first hurdle. I was unaware that the title needed to fit the sidebar and now that I know I can't find any reference to the number of characters allowed in either the Contribute your Knowledge item or the DokuWiki article about the Sidebar.

I think that I may have some skills to offer as a rookie user!

Brian

[tatewise]

Brian, I was being a bit economic with the truth.
There is no absolute limit, but if the Title is too long it wraps on to a second or third line in the sidebar.
You can see that effect if you shrink the browser window small enough.
It just looks neater if it fits onto one line on a reasonably full size browser window.
But the sidebar entry does not have to be identical to the page Title, c.f. FH V5+ Plugins => Family Historian Plugins

[ColeValleyGirl]

Mike, I think your memory may be playing tricks about how long it took us to restructure the 'Contribute Your Knowledge' section -- the relevant forum thread is at Contribute Your Knowledge Improvements (16381). It was a year elapsed, but it was not a year of work.

You and I started discussing the shortcomings of that section on 12 November 2018 (based on my less-than-satisfactory experience on finding information I needed which you thought was hiding in plain sight).

By November 13 we had moved on to discussing how it might be restructured.

By November 17 we were starting to implement our ideas in a set of pages parallel to the live ones; the target structure continued to evolve as we worked and could see what made sense and what didn't.

The two of us continued to collaborate on content and structure until Dec 17 (one elapsed month after the draft structure was agreed). Over the Christmas/New Year period we took a break; you then weren't able to come back to it until 17 November 2019, and the new pages went live on December 7th. It could have happened much earlier, leaving some final touches to be done, which is always the way with a KB, but I wasn't confident with the final steps involved in putting it live and retiring the old content. Ironically, we didn't cover that in the documentation we produced but if any restructuring is planned in the current KB, there will need to be some guidance produced so one individual is not a bottleneck.

So just over a year elapsed end-to-end but 4-6 weeks of actual (sporadic) work.

Scaling that up to the Family Historian section: 1 year of work if we were doing it on the existing platform. Migrating to a new platform should be easier (or why would we do it?), especially if we can script some elements of the migration.

-----

I learned quite a lot from revamping the Contribute Your Knowledge section.

1. Creating content should be straightforward. On the present platform it’s cumbersome, and involves learning a platform that I will never use anywhere else (even if I had the opportunity, I might choose to shoot myself first). I still can't generate even simple content without having the 'Contribute Your Knowledge section' open as an aide-memoire, and I'd consider myself a very experienced web content-creator. I'm not surprised that few people contribute once they understand what is involved. Minor edits to existing content is comparatively easy but not problem-free -- there are all sorts of gotchas, especially for those unfortunates with experience of more modern platforms.
2. Restructuring page/sections should be easy. On the present platform it’s a nightmare; and creating the links, indexes etc. that should help users move around it is a manual task and so prone to error. The whole edifice depends on editors remembering the right magic incantations to put in at the right places.
3. Maintenance should be easy. In particular it should not depend on a single person. (Or 2, but one is heavily committed elsewhere).
4. A widely used modern platform is needed to support 3. The platform for our KB is 20 years old, and maintaining and updating it is critically dependent on a single person, even if it claims to be 'open source'.
5. The KB must provide a high “hit rate” for all users to get their answers. The user’s first two keystrokes must inspire confidence they’re delving into the KB in the right direction. Our current KB structure is not fit for purpose -- for an inexperienced user looking for an answer to a focussed question, finding that answer is hit and miss. Did the content creator remember the magic incantations? Has the user read the mind of the content creator, so they know what to search for? Is the user willing to wade through multiple pages to find the simple answer they were looking for? Or will they fall at the first hurdle and go: sod it, I won't bother... or I'll ask at the forums and be chastised for not navigating all the way through the labyrinth to the answer I need and/or for not having the right learning style. We must also learn from and act promptly on feedback from users if finding their answers proves elusive, incomplete or unclear.

In summary: the current platform is (a) not fit for purpose for content creators or consumers; (b) introduces risks we should not be willing to run; (c) is too dependent on individuals with unique experience.

----

So, a new platform is where we're headed.

Jane wants to move to a WordPress platform as a strategic choice, supplemented by plugins that support a best-practice knowledgebase (with all the baked-in features that entails). She has identified a starting point (Wordpress, Pods, maybe EchoKnowledgeBase) -- already spun up for me to prototype -- and I shall spend some weeks prototyping/refining the platform. Within a year (give or take) we will be migrating to a WP-based solution -- hopefully earlier, depending on when we have a stable platform.

Using Wordpress will allow us to leverage the skills of content creators with relevant skills (people who already use WP or another modern content management system such as Drupal -- yep, that's me) as well as people who want a simple intuitive interface to add their knowledge.

Wordpress is so widely used we're unlikely to run out of support, or to end up dependent on a single expert who understands the platform.

Wordpress plus add-ins allow us to automate adding content and links in the right place, easily modify structure, have unpublished content for work-in-progress... in short, have all the content-management features of a modern content-management system.

----

Yes, but it's all hard and difficult.

We can script some migrations, especially if work has been done in the current KB to restructure things according to a new set of style and structure guides. Ditto download links.

We can progressively migrate content in the old KB and leave links behind that point to the new KB, so the two co-exist.

I still think the opportunity to review aged KB content with a critical eye to our style and objectives is invaluable.

----

Why not just restructure what we've got?

The current platform has unacceptable risks. And it doesn't have a long-term future. It isn't an option to maintain the status quo.

However, some restructuring on the current platform (and editing to conform with a new style guide) would ease the migration.

[Valkrider]

I have stayed out of this discussion for now but seeing the comments about moving to Wordpress with EchoKnowledgebase has caused me to comment.

I think that this will be a good move. It will be easier to create and update the knowledgebase than the current wiki which I find a PITA to deal with and as a result I have done very little updating / creating of content. I think the whole Mac section needs a re-write as it has grown like topsy and is fragmented but I don't have the will to do this with the current software. However, stick it on Wordpress, with which I am very familiar with over 30 sites that I have created and look after as well as my own Wordpress gedcom plugin I will be more than happy to help with the migration and subsequent maintenance.

So when it is ready please let me know and I will help.

[tatewise]

Helen, you are probably correct, and only about 6 weeks elapsed of actual work, but I felt we were quite busy.
Also, we are not getting any younger and life events do get in the way sometimes.
So let us assume the new platform will be 50% more effective.
That means 10 pages will take about 6 person weeks, i.e. 50% of 6 weeks x 2 people.

I still maintain that we must recognise the extent of the work being proposed.
Taking that estimate means the Family Historian 180 pages will need 180 / 10 * 6 = 108 person weeks.
But the rest of the Knowledge Base has 900+ pages, of which about half are Downloads & Links related pages.
Those are almost all FH related (Plugins, AS, Glossary, Downloads & Links).
So that leads to a total of about 650 person weeks, unless we can devise some effective migration scripts.
If not, even with 6 people, that is around 2 years elapsed time.

So, some restructuring of the current platform would benefit in two ways.
Firstly, current users would discover answers more easily during those 2 years.
Secondly, we might discover what styles work best.

[ColeValleyGirl]

Valkrider just did a test migration of one page and it took minutes.

[tatewise]

Fine, but we are not just talking about migration, but mainly some significant restructuring.
It was similar restructuring that was the focus of our 12 person weeks work. We did not have to perform any migration.
Judging by some of the recent comments here, even that restructuring is not to everyone's liking.

The restructuring needed for the much more complex intertwined FH pages won't be as easy!
One aspect of that, which I struggle with, is how to cope with the features of different versions of FH.
There appear to still be users of V3, V4 & V5 and with V7 will just get more complex.
Whole new features such as FH V6 Place Records & Mapping are not so difficult, but do impact Data Refs in various ways.
It is where minor variations exist within an established feature that gets more awkward.

Maybe that is where our choice of intended audience can have an impact.
Do we perhaps only provide advice for the latest FH version, and earlier version users will have read between the lines.
That might encourage such users to upgrade.
However, it would need the animated tutorials to be reviewed and some updated for each major FH version.
Most of the current ones date back to V3 and V4.

[Valkrider]

Mike following on from Helen's reply.

I had no experience of EchoKlowledgeBase but plenty of Wordpress experience. I have a development site so just installed it on that and once it was installed I selected create a new article went to the existing KB and just did a copy then pasted it in to the article and saved it. Took about 30 seconds I then published it and that was it. If you want to take a look at what it looks like now it is at http://dev.orba-design.com/knowledge-ba ... an-on-mac/. It needs reformatting and a bit updating but those could be done as and when once the migration was complete. The default styling sorted but those would need to be tweaked but that would be a one off exercise for the whole KB.

Obviously this is a task that will take some time to complete but if we started on the popular items first that would be of most benefit to most users first.

Like anything that is designed there will always be those who want something different and that is one of the challenges of design by committee. I suspect that the design would have to be a compromise and some people may not get exactly what they want.

[tatewise]

Thank you Colin, that migration process does work quite well, but as you say will need to be tweaked.
I imagine it mostly involves just copying the HTML from page to page.
For example, will all the hyperlinks to the FHUG Wiki (including screenshot images) be able to be 'tweaked' globally so they refer to the WordPress platform, or will each one need to be edited by hand?
Notice that the within page hyperlink to Reported Problems in 3rd paragraph did not 'migrate'.
I suspect wiki features such as the Related Pages backlinks, and Index page entries will not 'migrate'.

Anyway, that is the 'easy' bit, and would simply duplicate the same accessibility problems we are trying to improve.
It is the reorganisation task that will take the majority of the effort, whichever platform is the host.
I accept that may be easier on a newer platform that may encourage more contributors, but still a significant task.

[Jane]

I should be able to automatically move downloads and web links into their own areas, so they do not pollute to main knowledge area and the same with the Code Snippets. I suspect when I get a spare day I can code reasonable conversions, with just some tidying of any unusual ones.

Image urls still point to the original upload location, but a script to move them all over should be straight forward to write.

The old Wiki can be left in places for things like plugin help which at the moment make the search very inefficient.

Ancestral sources documentation can also be done as a separate "area" at a later date.

Once V7 is out, my intention is to redo most of my existing Videos to the new release.

Tags will be supported, related posts are supported in Wordpress, but they do not work quite like backlinks.

At the moment Helen is experimenting with Wordpress for me, as my day job is pretty hectic, so won't have time to jump in to answer questions here for a while.

[davidf]

...
Judging by some of the recent comments here, even that restructuring is not to everyone's liking.

The restructuring needed for the much more complex intertwined FH pages won't be as easy!
One aspect of that, which I struggle with, is how to cope with the features of different versions of FH.
There appear to still be users of V3, V4 & V5 and with V7 will just get more complex.
Whole new features such as FH V6 Place Records & Mapping are not so difficult, but do impact Data Refs in various ways.
It is where minor variations exist within an established feature that gets more awkward.

Maybe that is where our choice of intended audience can have an impact.
Do we perhaps only provide advice for the latest FH version, and earlier version users will have read between the lines.
That might encourage such users to upgrade.
However, it would need the animated tutorials to be reviewed and some updated for each major FH version.
Most of the current ones date back to V3 and V4.

I probably ought to plead guilty to Mike's concern that previous work is "unappreciated" or not to one's liking. But the alternative is to turn one's back - and this thread started because I was sensing Mike's understandable frustration that people were turning their backs.

I have held off making too many changes myself because

1. I feel uncertain about my technical skills to do anything significant - the work last year on To-Do Lists was surprisingly tricky and I am aware that others have probably held off criticising my technical implementation.
2. I am concerned that I (with a post count orders of magnitude fewer than others) do not have a mandate to impose my views on others - particularly when others are heavily invested in previous work.
3. I am wary of just spinning a bit more complexity in to what has already been described as "complex intertwined" and a bit of a rats nest.

Whatever "platform" decisions are made we face a need to update; some of the animated tutorials (which I guess are high development input) are now so old as to be possibly misleading as is much of the other FH4 oriented work; we are faced with FH7 in a few months.

Can the current structure support further ad hoc updates - or is there a danger that we just create something even more impenetrable as we insert "switching links" (FH7 users this way, FH6 users that way, Previous versions? Go and look at the legacy KB?)

I think the danger is that we could make it worse and the result will see even less use. Do we get "page impression" stats or routing details so that we can see how people are using what we have. (My suspicion is that most use may come direct from following links that Mike gives in his forum replies - certainly would apply to my use of the knowledge base as a source of solutions to using FH. Perhaps we should conclude that this is actually quite an efficient modus operandi )

But we must ensure that anything we do makes the result better. That is one reason why I have mooted the idea of some form of style guide and some agreement on outline structure - they may not be the right words to ring the right bells with other contributors.

FH7 will require new content. Can we reach any agreement as to how we would create that content almost as a stand alone KB - we can't just stick it under How To Guides: > Family Historian > Family Historian Latest Changes (That area of the structure appears to have a very different use). If that works we can then back fill with similarly styled/structured content relating to the major features of FH6 and FH7. We may be able to reuse some/much of what we already have but not without some heavy rewriting.

These considerations are platform independent, but a platform change may be an opportunity to think again about style and structure.

[ColeValleyGirl]

David,

I'm with you all the way on a style guide and structure... And moving to WP gives us structuring opportunities we have previously lacked. We can have multiple taxonomies for an article -- say Topics/Subtopics to group content by subject area; and FH version(s); and Skill level. And articles can have multiple subject areas. And if we decide they're in the wrong topic area, we change it with tick boxes.

We can also have better search and filtering facilities -- show me all articles in the Backup subtopic that apply to FH5 and later -- which may be an excellent opportunity to break currently long and complex pages into a number of smaller tightly-focussed articles which are associated with each other via tags and taxonomies, while still leaving room for 'In depth' articles that survey the entire panorama of a subject for a different target audience/learning style, and delve into the nitty gritty technical detail. We can even mark such articles as "In Depth" to serve as a warning or enticement to users depending on their tastes. (We will have to think about the perils of duplication/contradiction between In Depth and non-In Depth material.)

Do you have some thoughts about what should be in our style guide that we can spin off into a separate forum topic? I've already volunteered to work out an outline structure.

[ColeValleyGirl]

Towards a style guide for the new Knowledgebase (17458)

I've moved this to a new topic so it doesn't get drowned in the more general discussion.

[tatewise]

Referring back to Lorna's suggestions for improving the Index back on 7th Feb, I have added those entries and Jane has refreshed the wiki to build them into the Index together with several others that were pending.

See if the alphabetic_index|> Knowledge Base Index is now getting more useful.

The necessity to 'kick' the wiki manually to refresh certain cross-references is a drawback of this platform.

[LornaCraig]

Mike, yes I think the index is steadily getting more useful.

One thing I have just noticed is that there is a full list of Workspace Windows but some of these could benefit from (additional) separate entries in the index. The word 'Workspace' might not come readily to mind for many users, and they may not find it by chance because it's right at the end of the index. People are more likely to look for the name of the window.

The words Focus and Map don't have their own entries in the index, with or without the word Window after them.
Other words (Records, Diagram, Media, Report, Book...) do appear but not in the context of the window of that name, and some of the links are different from the ones in the Windows section. For example the Workspace Windows > Records Window section has a link to Customise or print Records Window Columns, but that can't be found under Records.

Looking at words which appear in the subject titles of topics in the Forums suggests a few more:
Registration key
Sentence templates
Reports not displaying correctly (running on Mac)

[tatewise]

I've added those Index entry tags Lorna, but they won't appear until Jane next refreshes the wiki.
I don't want to ask her again so soon.

[LornaCraig]

Thanks. A few more have come to mind:

Addresses link to Places and Addresses page
Geocoding ditto
Also add this to Place Records which only has one link at present
Witness Roles

Questions about these often come up in the forums.

[tatewise]

Those Index entry tags are done Lorna.

[tatewise]

Remember that the alphabetic_index|> Knowledge Base Index was introduced to help with topics that cannot easily be found by a Knowledge Base Search or in the knowledge_base_titles|> Knowledge Base Titles where the first word or two identify the topic.