* Improving the Knowledge Base

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.
Post Reply
User avatar
RogerF
Famous
Posts: 182
Joined: 26 Apr 2009 16:32
Family Historian: V6.2
Location: Oxfordshire, England
Contact:

Improving the Knowledge Base

Post by RogerF »

I recently uploaded a handful of Queries to the FHUG Knowledge Base, and was surprised at the difficulties I had. Not technical glitches -- everything (eventually) worked fine; rather, it was hard to discover full details of the steps involved. Obviously part of the problem is my ageing brain, but I think there's also an issue with the current documentation making too many assumptions.

I've explained my experiences to the ever-helpful Mike Tate, who I know is more than happy with any attempt to make the KB more user-accessible. So, this is a request for feedback. Do you use the KB? Does it answer your questions? What couldn't you find there? What would make the KB even more useful? Are there aspects of FH where the KB could be a lot more helpful? Please think broadly; a small problem is still a problem.

And the key question: are you willing to participate in a collaborate exercise to make the KB more approachable? 'Participate' in the broadest sense: mention problems; suggest solutions; review explanations; improve the existing material. No sensible offer refused. Thank you.
Roger Firth, using FH to research the FIRTHs of Lancashire and Yorkshire, and the residents of the market town where I live.
User avatar
tatewise
Megastar
Posts: 28341
Joined: 25 May 2010 11:00
Family Historian: V7
Location: Torbay, Devon, UK
Contact:

Re: Improving the Knowledge Base

Post by tatewise »

Sadly Roger, there have been no 'offers' so far.

I recognise there was a gap in the advice regarding updating the downloadable Query files.

But apart from that, what were the main difficulties you had to discover full details of the steps involved?

BTW: I have made some minor updates to the following pages to add some new clues:
contributeyourknowledge:about|> About Contribute Your Knowledge
contributeyourknowledge:pageformattingsyntaxreference:links#download_links|> Download Links mentioned in fhugdownloads:add_downloads|> How to Add Downloads and Links
contributeyourknowledge:pageformattingsyntaxreference:images|> Page Formatting ~ Image Files
links:add_a_link|> Add a Member Web Site Link
Mike Tate ~ researching the Tate and Scott family history ~ tatewise ancestry
User avatar
RogerF
Famous
Posts: 182
Joined: 26 Apr 2009 16:32
Family Historian: V6.2
Location: Oxfordshire, England
Contact:

Re: Improving the Knowledge Base

Post by RogerF »

Sad, but not unexpected. You ask about the issues I had when first uploading a Query to the KB. From memory, in no particular order, and entirely my subjective opinion:

1. The "Add Family Historian or Ancestral Sources Download Form" is confusingly named; it implies I'm about to download a copy of FH or AS. Something like "Add a downloadable query or similar" would be a lot clearer.

2. The form asks for the download's title. Perhaps a note that the value supplied will be automatically prefixed with "Query:Individual ~ " or equivalent?

3. The form generates a partly-populated Query overview page. It would be helpful if the "Description" field indicated the convention of providing not only a brief description of the query's purpose, by also the submitter's username and the date. It would also be helpful if the User Comments field was fully populated.

4. The need for a User Group message asking Jane to update the indices is a welcome addition.

5. The need to use Media Manager to update the downloadable query needs to be more prominent. Specifically it should appear on the Query overview page, because that's where you naturally go to update any other aspect of the Query.
Roger Firth, using FH to research the FIRTHs of Lancashire and Yorkshire, and the residents of the market town where I live.
User avatar
tatewise
Megastar
Posts: 28341
Joined: 25 May 2010 11:00
Family Historian: V7
Location: Torbay, Devon, UK
Contact:

Re: Improving the Knowledge Base

Post by tatewise »

Thank you for your feedback. I hope I have made some positive changes.
  1. The fhugdownloads:add_downloads|> How to Add Downloads and Links page and its Data Entry Forms pages have been revised. Your comments are welcomed.
  2. The fhugdownloads:contents:add_download_form|> Add a Downloadable File and fhugdownloads:contents:add_link_form|> Add a Link to a Service or Utility pages now have a note regarding titles, plus other revisions.
  3. Since the introduction of the forms, the convention of listing the author name and date was dropped. They can be discovered by using the Tools > Old revisions option available to all, and gives a history of all changes.
    Yes, the FIXME advice in User Comments needs to be added to the form templates, which is a job for Jane.
  4. OK.
  5. Users other than the author might find Media Manager advice confusing in the download pages.
    It would be a mammoth task to add it retrospectively to all existing download pages.
    The fhugdownloads:contents:add_download_form|> Add a Downloadable File page could give more detailed Media Manager advice.
Mike Tate ~ researching the Tate and Scott family history ~ tatewise ancestry
User avatar
RogerF
Famous
Posts: 182
Joined: 26 Apr 2009 16:32
Family Historian: V6.2
Location: Oxfordshire, England
Contact:

Re: Improving the Knowledge Base

Post by RogerF »

OK Mike, thanks for your positive response.

Just a thought: would it be helpful to create an "Improving the KB - overview" page which (a) welcomes input from all and sundry, and (b) summarises in one place each of the steps needed to edit existing pages, and to add new ones? Just brief numbered lists, linking to the fuller-detailed nitty-gritty.
Roger Firth, using FH to research the FIRTHs of Lancashire and Yorkshire, and the residents of the market town where I live.
User avatar
tatewise
Megastar
Posts: 28341
Joined: 25 May 2010 11:00
Family Historian: V7
Location: Torbay, Devon, UK
Contact:

Re: Improving the Knowledge Base

Post by tatewise »

As a matter of interest, what sections of contributeyourknowledge:index|> Contribute Your Knowledge did you visit before attempting any editing?

I have added some Quick Start Steps to the contributeyourknowledge:beginnersuserguide|> Contribute Your Knowledge > Beginners User Guide. Is that anything like what you expected?

BTW: You could always edit the KB and add such advice yourself ! ! ! :)
Mike Tate ~ researching the Tate and Scott family history ~ tatewise ancestry
avatar
jbtapscott
Megastar
Posts: 513
Joined: 19 Nov 2014 17:52
Family Historian: V7
Location: Corfu, Greece
Contact:

Re: Improving the Knowledge Base

Post by jbtapscott »

I've been pretty much offline for the last week or so and am only just catching up on FHUG postings, but I am quite happy to participate in any exercise to improve the KB articles. I have to admit I have not made a great deal of use of them as I have tended to keep "playing" with the sample database until I have found a way to get what I want, and also have not always found the KB to be particularly helpful on the odd occasion I have accessed it (I am a recent TMG convert).

When I was working, one of my responsibilities was the maintenance of a (large) user guide for a major financial software application and one of the tacks I took with that was to keep a log of all user questions / emails, etc., so that I could establish places where the UG could provide more useful / better information. Perhaps I'll go down the same route with the KB as I find things I cannot find an answer for / think there is a better (simpler) explanation for a problem than that found in the KB.
Brent Tapscott ~ researching the Tapscott and Wallace family history
Tapscott & Wallace family tree
User avatar
RogerF
Famous
Posts: 182
Joined: 26 Apr 2009 16:32
Family Historian: V6.2
Location: Oxfordshire, England
Contact:

Re: Improving the Knowledge Base

Post by RogerF »

Mike: As a matter of interest, what sections of Knowledge Base > Contribute Your Knowledge did you visit before attempting any editing?
ALL of them, Mike, all of them.
Mike: I have added some Quick Start Steps to the Knowledge Base > Contribute Your Knowledge > Beginners User Guide. Is that anything like what you expected?
And here you kindly illustrate the problems that I've been experiencing. Step back and take a look at About Contribute Your Knowledge and at Beginner's User Guide. If you're me, you'll see much the same sort of thing being said twice, only in different words and with different emphasis, making the whole thing seem more complex than it is. IMHO, one of the key rules of technical documentation is to spell out the detailed procedural steps ONCE, where they can be easily maintained, and then link to that procedure wherever it seems useful. The KB doesn't do this, and I think that's at the heart of my issues.
Mike: BTW: You could always edit the KB and add such advice yourself ! ! ! :)
You may not realise it, Mike, but you cast a very long shadow. I would feel, shall we say impertinent?, in editing something you've written. I know you want the KB to be freely editable, but trust me, it's not that easy.

BTW, I'm puzzled about the advice on Tools > Log in and Tools > Log out. I don't do this; it happens automatically.
Roger Firth, using FH to research the FIRTHs of Lancashire and Yorkshire, and the residents of the market town where I live.
User avatar
tatewise
Megastar
Posts: 28341
Joined: 25 May 2010 11:00
Family Historian: V7
Location: Torbay, Devon, UK
Contact:

Re: Improving the Knowledge Base

Post by tatewise »

I take your point and have reduced the amount of duplication, although I often find that other Wiki typically do say similar things in different places, but perhaps it is best avoided in technical procedures.

I do recognise my 'shadow' and I also accept that I find it difficult to put myself in the position of newcomers, and present a rounded picture, so welcome feedback. Anyone with experience of user guide or technical writing should be able to improve the KB significantly. There is also a routine task of keeping the KB up-to-date as FH and AS evolve. If more of 'us' were able to help, then it would become an easier task.

Regarding Log In and Log Out, like other website accounts, if you never Log Out then when you return you are still logged in, and the Edit buttons will always be present. Personally, I prefer to Log Out and only Log In when editing, but it is a personal preference. However, for a beginner, it is important to emphasise that they must Log In before they can Edit.
Mike Tate ~ researching the Tate and Scott family history ~ tatewise ancestry
User avatar
RogerF
Famous
Posts: 182
Joined: 26 Apr 2009 16:32
Family Historian: V6.2
Location: Oxfordshire, England
Contact:

Re: Improving the Knowledge Base

Post by RogerF »

Thanks, Mike. Things are starting to look a lot better. What now strikes me is the pages Contribute your Knowledge and About Contribute your Knowledge are effectively saying exactly the same thing. Could the About... simply be abandoned?
Roger Firth, using FH to research the FIRTHs of Lancashire and Yorkshire, and the residents of the market town where I live.
User avatar
Jane
Site Admin
Posts: 8508
Joined: 01 Nov 2002 15:00
Family Historian: V7
Location: Somerset, England
Contact:

Re: Improving the Knowledge Base

Post by Jane »

I have added FIXME to the template, but I do wonder if that is the best solution as soon users might interpret that as implying the download is broken, also as we limit access to editing on the Knowledge base would it be better to remove the user comments section completely?

Editors could of course add it back in if needed.
Jane
My Family History : My Photography "Knowledge is knowing that a tomato is a fruit. Wisdom is not putting it in a fruit salad."
User avatar
RogerF
Famous
Posts: 182
Joined: 26 Apr 2009 16:32
Family Historian: V6.2
Location: Oxfordshire, England
Contact:

Re: Improving the Knowledge Base

Post by RogerF »

I would be in favour of removing it, Jane, as long it was clear to users how to communicate problems and suggestions back to the creator.
Roger Firth, using FH to research the FIRTHs of Lancashire and Yorkshire, and the residents of the market town where I live.
User avatar
tatewise
Megastar
Posts: 28341
Joined: 25 May 2010 11:00
Family Historian: V7
Location: Torbay, Devon, UK
Contact:

Re: Improving the Knowledge Base

Post by tatewise »

There appear to be several options:
  1. Retain the User Comments section with FIXME: You are welcome to add comments here. which is what the vast majority of existing fhugdownloads:index|> Downloads and Links already contain, and appears to be quite clear, since I am not aware of any users misunderstanding what that means.
  2. Remove the User Comments section everywhere, and rely on users posting in the Forums as they regularly do with problems and suggestions for any pages in the KB.
  3. Add a message that instructs users to post problems and suggestions in the Forums. BUT would this be just on the introductory category pages, or added retrospectively to every existing fhugdownloads:index|> Downloads and Links page, as well as the template, in place of the User Comments section?
@ Jane: Does the template include FIXME: You are welcome to add comments here. or just FIXME which would be misleading?

@ Roger: I would prefer to keep the main Contribute Your Knowledge page as well as the About Contribute Your Knowledge page to be consistent with all the other How To Guides structure that similarly have an About... page as described in contributeyourknowledge:knowledgebaseeditingreference:activesections|> Knowledge Base Editing ~ Active Sections together with Introduction and Changes, FAQs, Index sections.
Mike Tate ~ researching the Tate and Scott family history ~ tatewise ancestry
User avatar
Jane
Site Admin
Posts: 8508
Joined: 01 Nov 2002 15:00
Family Historian: V7
Location: Somerset, England
Contact:

Re: Improving the Knowledge Base

Post by Jane »

===== User Comments =====
FIXME : You are welcome to add comments here
Jane
My Family History : My Photography "Knowledge is knowing that a tomato is a fruit. Wisdom is not putting it in a fruit salad."
Post Reply