* 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
Megastar
Posts: 951
Joined: 17 Jan 2009 19:14
Family Historian: V6.2
Location: UK

Towards a style guide for the new Knowledgebase

Post by davidf »

ColeValleyGirl wrote: 10 Feb 2020 18:21 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.
Had a feeling that would come!

I am not yet ready to propose "a draft style guide", but am conscious of a few issues which I think it is worth a kick around so that we are roughly of one mind. If this takes off it can be lifted into a different topic.

I think the style guide could usefully work in two directions
  • User Guide and How to type pages
  • In detail functional reference pages
Force fitting a style guide for one of the above on to the other is unlikely to be profitable? With wikis/community contributed web sites you cannot be prescriptive; the guide has to be that: guidance (agreed by some form of consensus) as to what make something accessible, useful, and maintainable?

For the moment I don't think we need to try to "legislate" for proper use of commas, correct capitalisation or appropriate use of numerals etc.. Those issues are second order compared to creating contant which serves the above purpose.

So for User Guide and How to type pages - a starter for possibly 5:
  • The Above the Fold area should
    • Unambiguously define what the page is about and redirect for (1) common misapprehensions (2) "expert" readers
  • Page Structure. Ideally
    • Pages should follow our normal linear reading process
    • A page should contain a complete "chunk" of knowledge and not require diverting away to another page and returning
    • Page Sections (clearly format defined) can if necessary start with a paragraph explaining what the section aims to do and offer a "skip link"
  • Language
    • Language needs to be plain and pitched at the sort of person who might try to do genealogy - an understanding of most common genealogical terms can be assumed - but that does not apply to IT terms.
    • Sentences need to be short and if they are describing a process should use bullet points or numbered steps
    • Most acronyms should be spelt out on first use in each page (or use something similar to the HMTL <abbr> tag)
    • We need to be alert to using technical terms (page-sections?!) that may be unfamiliar or misunderstood by non-expert users. Linking to a glossary page disrupts reading and readers may not bother to go and look but struggle on not fully understanding.
  • Images
    • Images assist understanding and make pages more digestible.
    • On a laptop images should preferably show the required detail without expansion. [What about tablets - are tablet users part of our audience? How we handle this could be platform dependent]
  • Navigation - I have seen some guidelines before, I can't recall where, but I think they included points like:
    • Page Navigation needs to take people quickly to the information they need; the more links the more opportunity to get lost
    • Too much navigation can be a distraction.
    • At the end of a page the navigation should anticipate where the reader wishes to go next; the next logical step, move to relevant part of Technical Reference, return to previous page
What other headings and style points would others think helpful?
David
Running FH 6.2.7. Under Wine on Linux (Ubuntu 22.04 LTS + LXDE 11)
User avatar
Valkrider
Megastar
Posts: 1563
Joined: 04 Jun 2012 19:03
Family Historian: V7
Location: Lincolnshire
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by Valkrider »

David & Helen

I have found a couple of KB style guides online which would seem to be a good starter for 10.

https://kb.uwstout.edu/88035 is a link to a webpage document.

This one is to a pdf download.
User avatar
ColeValleyGirl
Megastar
Posts: 5464
Joined: 28 Dec 2005 22:02
Family Historian: V7
Location: Cirencester, Gloucestershire
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by ColeValleyGirl »

David, I'm struggling to understand how you're segmenting the contents (How To, User Guide and In Detail), but it may just be a terminology difference.

I think we have 2 types of article:
  • How To: very short articles addressing a very specific question in short sharp list format (e.g. How to restore a backup?). They should contain a clear set of instructions to carry out the task concerned, with no digression or discussion.

    Target audience: People who know exactly what they want to do and why, and don't want distracting with extraneous content.
  • In Detail: Articles as long as they need to be to cover the breadth and depth of the relevant subject -- whether that subject is user-focussed (e.g. Backup and Recovery) or technically focussed (can't find an example on the current wiki of something that falls in this category but there may be something -- perhaps a dissertation on the Gedcom file format).

    Target audience: People who want to get a complete understanding of a topic, or who have questions after reading a How To article.
There are a number of things the Content Management System (CMS) can do to make it easier to comply with a style guide. For example, it can automatically add links to related content (articles in the same topic category) for those people looking for more detail or a different but related article; and also automatically link terms to a glossary and pop-up definitions of those terms so that the user doesn't have to leave the page to understand an unfamiliar term.
User avatar
tatewise
Megastar
Posts: 28333
Joined: 25 May 2010 11:00
Family Historian: V7
Location: Torbay, Devon, UK
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by tatewise »

Maybe examples of technically focussed topics are:
glossary:family_historian_program_data_folder|> Family Historian Program Data Folder
glossary:formal_database_structure|> Formal Database Structure

I'm being picky, but choosing How to restore a backup? as a How To example is unfortunate.
If you had instead chosen How to restore an FH Medium/Full Backup? then I'd have no argument.
That is because How to restore an FH Small Backup (GEDCOM Only)? is a different process, likewise FH Snapshot backups, and say Windows File History Backups.
Mike Tate ~ researching the Tate and Scott family history ~ tatewise ancestry
User avatar
Valkrider
Megastar
Posts: 1563
Joined: 04 Jun 2012 19:03
Family Historian: V7
Location: Lincolnshire
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by Valkrider »

Mike

This is surely a granularity thing so I would envisage it something like:

Restore from backup (This will be the top level without any content other than the links to below)
Then sub sections
FH Small Backup
FH Medium / Full backup
FH Snapshot backup
Windows Backup
Mac TimeMachine backup
then any any others
User avatar
ColeValleyGirl
Megastar
Posts: 5464
Joined: 28 Dec 2005 22:02
Family Historian: V7
Location: Cirencester, Gloucestershire
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by ColeValleyGirl »

Colin, I agree. The last thing anyone needs if they're desperately trying to workout how to get their data back is to be expected to understand all the nuances. The How To article has to lead them through understanding what they need to do, depending on what backup they have at hand.

However, I disagree fundamentally that the content of the article is just a list of links -- that's one thing that users find frustrating at present -- the number of pages they need to click through to find the answer to what they think is a simple question -- we need to be aiming for a maximum of two clicks (to topic area, to page) for people to get where they want to go, and then not expect them to leave that page to complete the task they want to do.

The article should have an (automatically generated) ToC at the top and include all the instructions without them needing to leave the page they've got to.
User avatar
davidf
Megastar
Posts: 951
Joined: 17 Jan 2009 19:14
Family Historian: V6.2
Location: UK

Re: Towards a style guide for the new Knowledgebase

Post by davidf »

ColeValleyGirl wrote: 12 Feb 2020 09:52 David, I'm struggling to understand how you're segmenting the contents (How To, User Guide and In Detail), but it may just be a terminology difference.
I am pretty certain that we are having a terminology agreement!

So below a "hack" of your post in which I have topologically inverted your approach!
I think we have 2 types of audience:
  1. People who think they know what they want to do and possibly why, and don't want distracting with extraneous content - they just want to solve their immediate perceived problem

    Types of Articles:
    • How Tos: very short articles addressing a very specific question in short sharp list format (e.g. How to restore a backup?). They should contain a clear set of instructions to carry out the task concerned, with no digression or discussion. We may have bits of this in the Beginners Guide Pages. Sometimes there is a need to pre-filter for situations where the specific question may not match the perceived problem.
    • User Guides: short introductions to a feature (e.g. FH6 mapping?) showing how a user can access the benefits of the feature probably with warnings of any "gotchas", but without massive detail - link at end for those "wanting more".
  2. People who want to get a complete understanding of a topic, or who have questions after reading a How To article.

    Types of Articles
    • In Detail: Articles as long as they need to be to cover the breadth and depth of the relevant subject -- whether that subject is user-focussed (e.g. Backup and Recovery) or technically focussed (can't find an example on the current wiki of something that falls in this category but there may be something -- perhaps a dissertation on the Gedcom file format).
    • Technical Reference: Often items such as a menu option by menu option explanation of exactly what is going on when an option is selected. We have this already deep in the current KB
ColeValleyGirl wrote: 12 Feb 2020 09:52 There are a number of things the Content Management System (CMS) can do to make it easier to comply with a style guide. For example, it can automatically add links to related content (articles in the same topic category) for those people looking for more detail or a different but related article; and also automatically link terms to a glossary and pop-up definitions of those terms so that the user doesn't have to leave the page to understand an unfamiliar term.
There is stuff that is "platform dependent" or "platform enforced" and given that "we" are having to choose between a restricted range of maintainable and hostable options, we don't want to write a style guide that becomes part of the specification for a system (and can easily become a red-line!).

That is partly why I am hesitant about proposing a draft for a style guide - and I like the initial heading Helen gave to this topic when she spun it out: Towards a style guide for the new Knowledgebase.

As I added to the initial post, we probably don't want an overly prescriptive style (when to capitalise, use commas etc.) in the manner of a publication's style guide; that can be very off putting to someone thinking of contributing and I think to readers is a second order issue (and besides someone can always tidy up such issues relatively quickly and easily).

The first order issue is that the style should be open and approachable - some sections of the Mailchimp Style Guide are possibly a good example of what we are trying to achieve (particularly for the first audience)? The links provided by Colin also touch on some of these points - although I am concerned (unnecessarily?) with being seen as too prescriptive by going into too much detail.
David
Running FH 6.2.7. Under Wine on Linux (Ubuntu 22.04 LTS + LXDE 11)
User avatar
davidf
Megastar
Posts: 951
Joined: 17 Jan 2009 19:14
Family Historian: V6.2
Location: UK

Re: Towards a style guide for the new Knowledgebase

Post by davidf »

tatewise wrote: 12 Feb 2020 10:15 Maybe examples of technically focussed topics are:
glossary:family_historian_program_data_folder|> Family Historian Program Data Folder
glossary:formal_database_structure|> Formal Database Structure
I would agree and would see these as the sort of articles that more advanced users would want to find. I think we need to be very clever in helping them find them - which may be more than just indexing!
tatewise wrote: 12 Feb 2020 10:15 I'm being picky, but choosing How to restore a backup? as a How To example is unfortunate.
If you had instead chosen How to restore an FH Medium/Full Backup? then I'd have no argument.
That is because How to restore an FH Small Backup (GEDCOM Only)? is a different process, likewise FH Snapshot backups, and say Windows File History Backups.
I think you raise an interesting example because users can be in different positions and actually requiring different types of restore, which might range from:
  • Undo
  • Restore snapshot
  • Restore a Data Backup
  • Restore an Installation
  • Restore and OS ++++!
Many users may not be over aware of the precise difference between a snapshot backup or one of the three backups (never having had to understand what goes in the project folder hierarchy). So a user approaching the knowledge base may not know what types of backups are available, what backups they have available, which type of restore they actually need and how to actually do the required restore. This is one of the reasons I am (rather clumsily) feeling my way to trying to advocate for page introductions to do a bit of pre-filtering to ensure that the reader gets directed to the right advice.
David
Running FH 6.2.7. Under Wine on Linux (Ubuntu 22.04 LTS + LXDE 11)
User avatar
tatewise
Megastar
Posts: 28333
Joined: 25 May 2010 11:00
Family Historian: V7
Location: Torbay, Devon, UK
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by tatewise »

Something seemingly innocuous as How to restore a backup? appears to pose some style issues with various opinions.
Maybe it is worth having a few strategic 'topics' against which to review style guide proposals in order to assess viability?
Then it may be easier to visualise the impact of the style on some actual examples.
Mike Tate ~ researching the Tate and Scott family history ~ tatewise ancestry
User avatar
Valkrider
Megastar
Posts: 1563
Joined: 04 Jun 2012 19:03
Family Historian: V7
Location: Lincolnshire
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by Valkrider »

ColeValleyGirl wrote: 12 Feb 2020 10:59 Colin, I agree. The last thing anyone needs if they're desperately trying to workout how to get their data back is to be expected to understand all the nuances. The How To article has to lead them through understanding what they need to do, depending on what backup they have at hand.

However, I disagree fundamentally that the content of the article is just a list of links -- that's one thing that users find frustrating at present -- the number of pages they need to click through to find the answer to what they think is a simple question -- we need to be aiming for a maximum of two clicks (to topic area, to page) for people to get where they want to go, and then not expect them to leave that page to complete the task they want to do.

The article should have an (automatically generated) ToC at the top and include all the instructions without them needing to leave the page they've got to.
Helen

I agree with you links are not great, I miss-wrote what I should have said is sections on the same page just like EchoKnowledgebase did with that page I knocked up with the links down the page to the appropriate section within the master document. It may make for long pages but providing the scroll is properly handled that should not be an issue.
User avatar
tatewise
Megastar
Posts: 28333
Joined: 25 May 2010 11:00
Family Historian: V7
Location: Torbay, Devon, UK
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by tatewise »

Being 'picky' again, but some are saying that long pages in a How To guide are unacceptable.
So How to restore a backup? is proving to be quite a good vehicle for discussing style strategies.
Mike Tate ~ researching the Tate and Scott family history ~ tatewise ancestry
User avatar
davidf
Megastar
Posts: 951
Joined: 17 Jan 2009 19:14
Family Historian: V6.2
Location: UK

Re: Towards a style guide for the new Knowledgebase

Post by davidf »

Is it worth picking up Mike's suggestion (which may resolve Colin & Helen's issue) and mock up something to do with "Recovery". Is it worth doing on the existing platform as even if we move (and I sense some momentum at the moment) we are trying to sort out what we might term "structural style"!?

So bullet pointing and not writing full sentences - the final thing would be a mix of sentences and bullet points.

Starting points (click 1):
  1. A user can't find their data
  2. A user knows they have screwed up and want to "roll back"
  3. A user has "lost the lot" (e.g. Hard disk failure or laptop theft)
Takes you to one of three pages:

1. I can't Find My Data
  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
  2. Introduction: This page tells you what to do if you have opened FH and the Project Window does not show your Family Tree Project ...
  3. [Explanation including Restore from Backup]
  4. Further Advice
    • Normal layout of FH Project files (including discussion of C & D drives)
    • Project Management Technical Reference
2. I've Messed up and want to get back to where I was

etc.
Last edited by davidf on 12 Feb 2020 16:45, edited 1 time in total.
David
Running FH 6.2.7. Under Wine on Linux (Ubuntu 22.04 LTS + LXDE 11)
User avatar
ColeValleyGirl
Megastar
Posts: 5464
Joined: 28 Dec 2005 22:02
Family Historian: V7
Location: Cirencester, Gloucestershire
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by ColeValleyGirl »

Mike, I'd say they were unacceptable without a mechanism to get to the right place with a very few clicks and ignore everything else, unless they haven't a clue where the right place is, in which case an escape-lane needs to be built in at the start to direct them (I suggest) to the forums rather than wandering the labyrinth of a knowledgebase getting more and more confused and desperate.

On the new knowledgebase, we will have the ability to:
  • Readily find a 'I've lost my data -- what do I do? How-to article applicable to their version of FH from the front page in one or two clicks (depending on whether we 'feature' that article, which I rather suspect in this case we would).
  • Read an introduction asking them what exactly the problem is, and what kind of backups they've got, and providing a link to the forums if they're not sure. (For some topics we may want to send people to the forums first as a default not an escape -- merging and splitting might be a good example where we ought to be discussing 'Why' with them rather than just saying 'How'.)
  • Use a ToC for the article that can link them immediately to a short sharp set steps that will work with what they have.
  • Provide links to other articles in the same topic at the end of the article in case they want to go further -- which would probably in this case include 'Setting up backups' as an In Depth article.
The alternatives would be a lot of Articles, one per backup type, which would make for shorter articles but reduce discoverabilty.

There are other scenarios in which a question without multiple possible answers will result in a much shorter Article.

Maybe we should say in the style guide that if the title is (or could be) 'How do I do this thing', then 'this is how you write it'.
User avatar
tatewise
Megastar
Posts: 28333
Joined: 25 May 2010 11:00
Family Historian: V7
Location: Torbay, Devon, UK
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by tatewise »

Helen's point about asking Why? instead of just offering How? arises quite often in the Forums.
Users perceive a solution to a problem, but are not quite sure how, because it is feature they have not used before.
So they post a question asking how to do something, but after a little interrogation they reveal the problem, and it often has a completely different solution.
If we make the How To guides too easy to follow without any caveats then those misguided users may just rush down the wrong rabbit hole!
Mike Tate ~ researching the Tate and Scott family history ~ tatewise ancestry
User avatar
ColeValleyGirl
Megastar
Posts: 5464
Joined: 28 Dec 2005 22:02
Family Historian: V7
Location: Cirencester, Gloucestershire
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by ColeValleyGirl »

Mike, I think you're focusing on a limited group of users.

If I want to know how to restore my data (Beginner level info), it's because I want to know how to restore my data -- please don't assume I'm an idiot.

If on the other hand I want to split a file, it might be appropriate to direct me to the forums or I might know what I'm doing. Really. So the Article needs to be written to include a frame challenge AND simple instructions for those for whom the frame challenge is not relevant.
User avatar
davidf
Megastar
Posts: 951
Joined: 17 Jan 2009 19:14
Family Historian: V6.2
Location: UK

Re: Towards a style guide for the new Knowledgebase

Post by davidf »

Helen, I think I have seen instances in the forum of where users want to restore their data, but it turns out that it is actually "there" and the problem is say they have managed to change the default location for their files. In this instance you restore their data not by using the "restore" option, but by "restoring" the default project location. If we do not capture issues like this we end up with restored "duplicates" sitting in non default locations.

I don't know if this is what you mean by "frame challenge" (have they framed their question appropriately)?
David
Running FH 6.2.7. Under Wine on Linux (Ubuntu 22.04 LTS + LXDE 11)
User avatar
ColeValleyGirl
Megastar
Posts: 5464
Joined: 28 Dec 2005 22:02
Family Historian: V7
Location: Cirencester, Gloucestershire
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by ColeValleyGirl »

Yes, that's what I mean by 'frame challenge' aka are they asking the right question.
User avatar
tatewise
Megastar
Posts: 28333
Joined: 25 May 2010 11:00
Family Historian: V7
Location: Torbay, Devon, UK
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by tatewise »

David is correct, and quite often users claim they have deleted FH and talk of re-installation, when they have actually upset/lost/deleted their Project. So, yes we need to very aware of 'frame challenges'.
Mike Tate ~ researching the Tate and Scott family history ~ tatewise ancestry
User avatar
ColeValleyGirl
Megastar
Posts: 5464
Joined: 28 Dec 2005 22:02
Family Historian: V7
Location: Cirencester, Gloucestershire
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by ColeValleyGirl »

That said, Mike, I think we also have to stop treating every user as if they didn't know what they were doing, so the langage of a frame challenge needs to be carefully thought through.
User avatar
tatewise
Megastar
Posts: 28333
Joined: 25 May 2010 11:00
Family Historian: V7
Location: Torbay, Devon, UK
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by tatewise »

When did we start treating every user as if they didn't know what they were doing?
Mike Tate ~ researching the Tate and Scott family history ~ tatewise ancestry
User avatar
jsphillips
Megastar
Posts: 582
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 »

As an ex Group Finance Director and in computers since 1964 I would like to say the following :-
Are you aware of the capabilities of the people who use this Base? One of the things in life I have learnt is not only to underestimate peoples capabilities but also not to flood them with Techie talk. I would hazard a guess that most people would use the base for simple things and therefore would expect a simple answer. "KISS"
I am aware that quite a few people have a great deal of knowledge but they are surely in the minority and would not be using the base anyway.
User avatar
ColeValleyGirl
Megastar
Posts: 5464
Joined: 28 Dec 2005 22:02
Family Historian: V7
Location: Cirencester, Gloucestershire
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by ColeValleyGirl »

One of the things in life I have learnt is not only to underestimate peoples capabilities but also not to flood them with Techie talk.
You may have seen that we're planning Articles at various levels -- some will be very simple instructions (hopefully useful to people of all technical experience) and some more detailed ones for the people who want that.
User avatar
ColeValleyGirl
Megastar
Posts: 5464
Joined: 28 Dec 2005 22:02
Family Historian: V7
Location: Cirencester, Gloucestershire
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by ColeValleyGirl »

When did we start treating every user as if they didn't know what they were doing?
We've all been guilty at some time or other of misreading a user's experience and patronising them, albeit inadvertently.
User avatar
tatewise
Megastar
Posts: 28333
Joined: 25 May 2010 11:00
Family Historian: V7
Location: Torbay, Devon, UK
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by tatewise »

But not EVERY user!
Mike Tate ~ researching the Tate and Scott family history ~ tatewise ancestry
User avatar
ColeValleyGirl
Megastar
Posts: 5464
Joined: 28 Dec 2005 22:02
Family Historian: V7
Location: Cirencester, Gloucestershire
Contact:

Re: Towards a style guide for the new Knowledgebase

Post by ColeValleyGirl »

But not EVERY user!
It's very easy to default to assuming ignorance, especially as it can feel like the safest thing to do. So, maybe not EVERY user, but every newly encountered user.
Post Reply