* Towards a style guide for the new Knowledgebase

Please only post suggestions and requests for help on using this web site here.

For help with FAMILY HISTORIAN itself please post in the Using Family Historian - General Usage Forum above.
User avatar
davidf
Superstar
Posts: 366
Joined: 17 Jan 2009 19:14
Family Historian: V6.2
Location: UK

Re: Towards a style guide for the new Knowledgebase

Post by davidf » 13 Feb 2020 16:38

In many cases you do want to assume that everyone coming to the KB has a level of ignorance - the key is how you do it!

We might assume that someone saying "I've lost my data" is ignorant of the various alternative scenarios, but we need not offend everyone by saying "really , are you sure that you have not just misplaced it?". We can ask a number of questions that the expert will skip through but the ignorant might read and think "Oh, yes that may be what my problem is"
  1. Pre-filter to check for "other problems"
    • Can't find the "main family tree file" [need precision] - Read on
    • Can't find some media files - Redirect
    • Can't get the file to run from backup [thinking of issues when people tried to open from the zip file] - Redirect/Read on?
    • FH seems to have disappeared - Redirect
    • Everything has gone - Redirect
David
Running FH 6.2.7. Under Wine on Linux (Lubuntu 18.04 LTS)

User avatar
ColeValleyGirl
Megastar
Posts: 1744
Joined: 28 Dec 2005 22:02
Family Historian: V6.2
Location: Cirencester, Gloucestershire
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by ColeValleyGirl » 13 Feb 2020 16:46

David, that's what I was trying unsuccessfully to say: some people will know exactly what their problem is, and some will not. You can easily offend (or at least wind up) the people who do know if you treat everybody the same -- just as you can confuse the people who don't know. You have to start out with a neutral position that alienates nobody.

User avatar
tatewise
Megastar
Posts: 18839
Joined: 25 May 2010 11:00
Family Historian: V6.2
Location: Torbay, Devon, UK
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by tatewise » 14 Feb 2020 12:04

Is it worth identifying a few well-understood recurring topics as benchmarks for the Style Guide?
Then we will have some practical examples against which the Style Guide advice can be assessed.
As How To topics I was thinking of:
  • How to re-install Family Historian?
  • How to migrate from another product?
  • How to output a Diagram on one PDF page?
  • How to restore a database backup?
They might also be reasonable topics for the Technical Reference.
Mike Tate ~ researching the Tate and Scott family history ~ tatewise ancestry

User avatar
ColeValleyGirl
Megastar
Posts: 1744
Joined: 28 Dec 2005 22:02
Family Historian: V6.2
Location: Cirencester, Gloucestershire
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by ColeValleyGirl » 14 Feb 2020 15:05

Thinking some more about how we might approach a 'How do I restore a Backup' Article... I think David's approach to redirecting early on in the article is right (rather than succumbing to article creep/bloat in an attempt to cover everything in one place).

So, for example:

The front page of the Knowledgebase could have a link to 'Restoring from an FH Backup' , which would be an article that sits within the 'Backup and Restore' topic (alongside perhaps 'Setting Up Backups', 'Working with Snapshots', maybe 'Backing up and Restoring Customisations and Preferences', ... )

Not all of these would be shown on the front screen, only topics that from experience we know will be searched for often; some would be under a link that led to all Backup and Restore topics but they would all be discoverable either via the topic hierarchy or from a search that takes titles, content and tags into account -- for tags think the words we have in the index at present. (There wouldn't be a separate partially-complete index to confuse people). An article will be able to have as many tags as we want, so when constructing an article it would make sense to cross-check with the index on the old knowledgebase to make sure that each article is as 'findable' as possible.

At the start of the article, the style guide could strongly recommend 'a statement of objectives/audience and some signposts to articles that might be more appropriate'. (We could mandate this in the article structure, but that might be going too far?)
Restoring from a FH Backup

This article describes how to restore data from a backup taken using FH's built in backup functions to recover a lost/deleted or corrupt project or file.

If you aren't sure that your file/project is unusable, only that FH can't see it any more, you should first review the article Why can't FH find my project? in case the data exists and is perfectly OK but FH has lost track of it.

If you want to undo some erroneous data entry you may find that reverting to a Snapshot will meet your needs -- review the article Working with Snapshots.

If you don't have a backup made with FH's built-in functions, you should review the article blah blah bla...

...etc...
Then the How-To article would provide concise instructions for restoring the various kinds of FH backup.

There would be an automatically-generated table of contents that would let users jump immediately to the section relevant to them if they know what it is.

At the end, the article author could provide links to external non-FHUG resources (if relevant) and the knowledgebase platform would generate links to 'Related Articles' based on the content of the current articles, its tags and topic area. (If we don't constrain an article as narrowly as we can, the list of related articles will get less useful/less focused.)

User avatar
jsphillips
Superstar
Posts: 459
Joined: 13 Aug 2006 16:00
Family Historian: V6.2
Location: Near Sevenoaks Kent

Re: Towards a style guide for the new Knowledgebase

Post by jsphillips » 19 Feb 2020 10:27

Great
I do think to allow for a spectrum of knowledge, that perhaps similar to classes I have held :-
Backup :-
Beginners. (Basics) .... Intermediate.....Advanced

Restore
Beginners.. (Basics) .. Intermediate...Advanced

This would allow those who have no knowledge not to be bamboozled by Techspeak or facts which have no immediate interest or relevance. But equally not to bore or cover known ground for those who have a greater knowledge. For those to learn all abilities then all 3 abilities can be viewed.

Also some screenshots of where to locate or where to "click" would be advantageous.

Post Reply