* Improving the Knowledge Base
- RogerF
- Famous
- Posts: 182
- Joined: 26 Apr 2009 16:32
- Family Historian: V6.2
- Location: Oxfordshire, England
- Contact:
Improving the Knowledge Base
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.
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.
- tatewise
- Megastar
- Posts: 28341
- Joined: 25 May 2010 11:00
- Family Historian: V7
- Location: Torbay, Devon, UK
- Contact:
Re: Improving the Knowledge Base
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
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
- RogerF
- Famous
- Posts: 182
- Joined: 26 Apr 2009 16:32
- Family Historian: V6.2
- Location: Oxfordshire, England
- Contact:
Re: Improving the Knowledge Base
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.
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.
- tatewise
- Megastar
- Posts: 28341
- Joined: 25 May 2010 11:00
- Family Historian: V7
- Location: Torbay, Devon, UK
- Contact:
Re: Improving the Knowledge Base
Thank you for your feedback. I hope I have made some positive changes.
- The fhugdownloads:add_downloads|> How to Add Downloads and Links page and its Data Entry Forms pages have been revised. Your comments are welcomed.
- 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.
- 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. - OK.
- 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
- RogerF
- Famous
- Posts: 182
- Joined: 26 Apr 2009 16:32
- Family Historian: V6.2
- Location: Oxfordshire, England
- Contact:
Re: Improving the Knowledge Base
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.
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.
- tatewise
- Megastar
- Posts: 28341
- Joined: 25 May 2010 11:00
- Family Historian: V7
- Location: Torbay, Devon, UK
- Contact:
Re: Improving the Knowledge Base
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 ! ! !
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
-
- Megastar
- Posts: 513
- Joined: 19 Nov 2014 17:52
- Family Historian: V7
- Location: Corfu, Greece
- Contact:
Re: Improving the Knowledge Base
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.
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
Tapscott & Wallace family tree
- RogerF
- Famous
- Posts: 182
- Joined: 26 Apr 2009 16:32
- Family Historian: V6.2
- Location: Oxfordshire, England
- Contact:
Re: Improving the Knowledge Base
ALL of them, Mike, all of them.Mike: As a matter of interest, what sections of Knowledge Base > Contribute Your Knowledge did you visit before attempting any editing?
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: I have added some Quick Start Steps to the Knowledge Base > Contribute Your Knowledge > Beginners User Guide. Is that anything like what you expected?
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.Mike: BTW: You could always edit the KB and add such advice yourself ! ! !
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.
- tatewise
- Megastar
- Posts: 28341
- Joined: 25 May 2010 11:00
- Family Historian: V7
- Location: Torbay, Devon, UK
- Contact:
Re: Improving the Knowledge Base
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.
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
- RogerF
- Famous
- Posts: 182
- Joined: 26 Apr 2009 16:32
- Family Historian: V6.2
- Location: Oxfordshire, England
- Contact:
Re: Improving the Knowledge Base
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.
- Jane
- Site Admin
- Posts: 8508
- Joined: 01 Nov 2002 15:00
- Family Historian: V7
- Location: Somerset, England
- Contact:
Re: Improving the Knowledge Base
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.
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."
My Family History : My Photography "Knowledge is knowing that a tomato is a fruit. Wisdom is not putting it in a fruit salad."
- RogerF
- Famous
- Posts: 182
- Joined: 26 Apr 2009 16:32
- Family Historian: V6.2
- Location: Oxfordshire, England
- Contact:
Re: Improving the Knowledge Base
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.
- tatewise
- Megastar
- Posts: 28341
- Joined: 25 May 2010 11:00
- Family Historian: V7
- Location: Torbay, Devon, UK
- Contact:
Re: Improving the Knowledge Base
There appear to be several options:
@ 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.
- 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.
- 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.
- 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?
@ 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
- Jane
- Site Admin
- Posts: 8508
- Joined: 01 Nov 2002 15:00
- Family Historian: V7
- Location: Somerset, England
- Contact:
Re: Improving the Knowledge Base
===== User Comments =====
FIXME : You are welcome to add comments here
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."
My Family History : My Photography "Knowledge is knowing that a tomato is a fruit. Wisdom is not putting it in a fruit salad."