Family Historian User Group

It does not appear to have been deleted properly so I would guess some kind of MySQL glitch.

Possible explanation: it looks as if Helen accidentally edited Mike's post instead of replying to it?

Regarding the ongoing discussions:

1. Introduction
   I felt the bit about "will be familiar to anyone who makes use of the Internet" might be a bit off-putting and I want to encourage even those who are not so familiar with hyperlinks to tackle simple editing.
   Some aspects of the KB hyperlinks are a little unusual, so the clarification is for relative novices:
   • internal links are orange instead of the more usual blue
   • all links always have a popup namespace tooltip (even if the target page does not exist yet)
   • internal links only link to another KB page
   That advice might also belong in home|> Knowledge Base Home or contributeyourknowledge:alternative_approach#basic_concepts|> Basic Concepts.
2. Links within the Knowledge Base
   I agree, but contributeyourknowledge:create_and_manage_pages|> Contribute Your Knowledge ~ Create And Manage Pages does not yet discuss the syntax options for namespaces and perhaps it should. Is it OK if I add a section on the very basics of namespace syntax?
   
   Regarding videos, I agree they should be relevant, but unless we intend to produce our own I suspect the choice is limited. Certainly some people learn better from videos than reading text. The videos may be a bit laboured to you and I, but perhaps not for a newcomer?
3. Family Historian link shortcuts
   I will experiment with a table for those too, but may be trickier as they need rather more explanation of the parameter values.
4. Linking an Image
   I have reviewed the image link options (I'd overlooked them) and that 1st sentence does make more sense now.
   However, for the benefit of the uninitiated, I think it needs an example of each link option that users can actually click on to see how they differ. Is it OK for me to add them when you are not editing?
   
   I'd not though of it before, but which one should we recommend users should choose?
5. Media Manager and Media Files Window
   I think having a screenshot accompanying explanations of buttons and options gives users a more comfortable feeling that they have at least reached the dialogue being described, and often it it reduces the descriptive text required.

BTW: Yes Lorna that may be an explanation. It fits the resultant posting. At that time I was also about to edit my posting and maybe some MySQL went haywire, because in that instant Helen's posting appeared.

Lorna, anything is possible -- however, I was constructing my reply for quite some time with Mike's original open in another window alongside it.... as well as the wiki entry we were discussing which weirdly got locked by (supposedly) Mike while I was editing it. Still, nothing lost.

I want to encourage even those who are not so familiar with hyperlinks to tackle simple editing.

How are they going to get to this point if they don't already recognise a hyperlink (including the fact that it's orange in the wiki) and how they behave? Your argument might have slightly more force if you were asking to introduce the html hyperlink syntax -- but they won't be using html to construct the links, so that's not useful either. I repeat: the info for novices ought to be in info about how to use/navigate the knowledgebase.

Is it OK if I add a section on the very basics of namespace syntax?

Ok -- let me know when I can review.

Videos: It's laboured because it's not a good video. Not well prepared/scripted. Not well focussed. The presenter even says he thinks it's too long. I'm not volunteering to produce any -- just suggesting that we ought to group videos in one place -- perhaps a separate section of 'How to' videos on the Overview Page structured d like the Overview and referred to in the Overview Introduction and then linked to as an additional resource in the relevant section on that page? Don't bury them in text a level down.

Family Historian link shortcuts

I think a table will work -- let me know if you want me to try first.

image link options

Is it worth the effort of constructing examples when we're suggesting people not use most of them -- have a look at the edits I've made.

Screenshots -- well, maybe, but if we're going to do them, we ought to do them everywhere -- and can we get a usable screenshot of those windows at a size that doesn't dominate the page?

I'm struggling with where to include the namespace syntax rules in contributeyourknowledge:create_and_manage_pages|> Contribute Your Knowledge ~ Create And Manage Pages, because that is only dealing with adding new pages, which only requires a small subset of the possibilities, so describing the full syntax is out of context.

I think it belongs in contributeyourknowledge:edit_links_and_media#links_within_the_knowledge_base|> Links within the Knowledge Base as a sub-section related to the phrase "(which you can also enter directly)".
This is the only place where a user might be inserting hyperlinks that refer to anywhere in the KB, and thus needs to know about absolute and relative namespace syntax. It also applies to namespaces associated with image & download media.
e.g.
:ns1:ns2:pg1 is absolute and refers to root namespace ns1 containing namespace ns2 and then page pg1.
.:ns2:pg1 is relative and refers to namespace ns2 within the current namespace.
.:pg1 and pg1 are relative and refer to page pg1 within the current namespace.
There are more, and the relative namespaces are particularly useful when moving a subsidiary namespace and its pages, into a different parent namespace, as it avoids having to correct all the hyperlinks, which would be necessary if they were absolute.

OK -- see if you can fit it in concisely?

Have you finished editing for the time being?

Yes, Mike.

Re namespace syntax I wonder if it might fit best here: Section Namespaces and be referenced from Links within the Knowledge Base

I'm not comfortable with putting the Namespace Conventions in Section Namespaces for two reasons:

1. The conventions are general Wiki Hyperlink rules, and nothing do to with how the KB namespaces are structured.
2. Users who add Hyperlinks need to know those conventions especially the recommended relative formats, but don't usually need to know about the KB structure, so directing them to that separate section would be confusing.

What I propose is to describe just a recommended subset of the conventions, so the section is much smaller.

I've created a table for Family Historian link shortcuts ~ Does it convey the necessary details?

Your revised Linking an Image recommendations work well.

Maybe the video can go in the main Reference Material section.

Mike, I'm concerned about the approach for namespace conventions for two reasons:

1. We're ending up with material about namespaces scattered -- at Create and Manage Pages, at Active Sections, at Creating a New Namespace and now at Namespace Conventions (and very likely at other places as well.) Where should be the one place that allows people to get a total overview of Understanding/Using Namespace.

2. The section you've added about Namespace Conventions follows directly on from advice to use the Link Wizard (for which you don't need to know the namespace conventions at all) -- there should at least be a preamble explaining why the subject has appeared. The terminology absolute and relative need explaining more clearly -- at least explain absolute as much as you explain relative.

Users who add Hyperlinks need to know those conventions especially the recommended relative formats, but don't usually need to know about the KB structure, so directing them to that separate section would be confusing.

I really don't understand how you can use the conventions without understanding the structure!

The new link shortcut table works well -- shall I delete the redundant examples underneath?

Re videos in the Reference Material section, I think that would be a good place to gather video links.

OK, let me try and explain, and then we can work out how best to present things.

1. Create and Manage Pages focusses on Pages (not namespaces) as stated in the very first sentence.
   It uses relative links such as [[One New Page]] and [[.:New Subsection:Index]] relative to the current namespace, because new pages are typically created local to the current namespace. The user does not need to know anything about the KB top level namespace structure to perform those operations. That is one of the major benefits of relative links.
   The Link Wizard does not help with creating those new page links.
   These operations are equivalent to Windows users creating files and subfolders within their account.
   
   It is only your Creating a New Namespace that involves the KB top level namespace structure, and I think that should be incorporated into the Active Sections page that needs to be associated with Expert Features. Novices should not go there. It is equivalent to messing with the Windows OS folders that only Administrators can access.
2. I've never used the Link Wizard but after some experimentation it appears to only be able to produce absolute links.
   They are necessary when cross-referencing from one part of the KB to another part of the KB.
   The Link Wizard is very helpful for that purpose as it navigates to and spells all the unfamiliar namespaces correctly for you.
   I admit the user needs to know the KB namespace names related to the top level headline titles, but most are obvious.
   
   The majority of Hyperlinks are relative links to the current namespace or its parent namespace, and these can only be entered manually.
3. The Namespace Conventions are only relevant to internal Hyperlinks and how they reference Pages or the similar references for internal Image and Download files. You don't need to know the KB structure to understand the conventions involving colons and dots, because they are just syntax rules that apply to any namespace hierarchy.
   In fact both the Wiki reference and I explain the conventions without mentioning the KB namespaces.
   They are similar to OS and HTML file naming conventions that use a similar dot notation for relative file paths.
4. The Active Sections explanation of the KB structure is only really needed for expert users who wish to modify it.
   For users who wish to create links across KB sections (typically to the Glossary), there may need to be a summary of namespace names versus section titles, but ideally they should be obvious, and with one or two exceptions I think they are. The main exception is how_to that should be familyhistorian.
   
   BTW: I think we need to find a new description for KB top level sections to avoid confusion with page section Headlines.
   Candidate names are chapters or divisions or segments.

Yes, delete the redundant examples underneath the new link shortcut table.

OK, I have vacuumed the cat (writer's slang) , cleaned the oven, put the rubbish out, changed the cat tray, inventoried the freezer, corresponded with two (putative) newly-discovered cousins about Joshua and the Battle of Jericho and here I am again...

We still need to keep in sight the need to have somewhere to go to understand 'everything' about the wiki structure aka 'name spaces and how to work with them'

Create And manage Pages is currently the place we introduce name spaces -- do we need a section before that on the 'wiki structure'?

Not my page on Creating a New Namespace -- I linked to an existing page and would be happy to bury it in Advanced stuff

Relative versus Absolute: I think you're fighting a losing battle, however desirable are relative links. Everything drives towards creating Absolute links (except for those who are editing the wiki day-in and day-out which is a vanishingly small number). The Link Wizards lets you create new pages -- navigate to the place you want to start from and type in the page name at the end of the namespace-- e.g. [[contributeyourknowledge:fred|Here's fred]]

And then of course there's the link icon that appears when you hover over a section heading -- another absolute link. The syntax may not work if copied and pasted (and we need to understand why and fix it) but it provides a link which you can use quickly with a little editing -- quicker than creating a link manually.

Namespace conventions -- make no sense until you understand the structure at which point you (as a frequent manual editor) can use them intelligently.

Active sections -- I question your assertion (well I would; I am a genealogist) that cross-links are rare or obvious without referring to a reference -- silo thinking. My research manage plugin is under how_to (because that's where similar methods are addressed, but it ought to cross-reference plugins. And a plugin I'm working on now should cross-reference Ancestral sources and how_to.

I do agree about terminology.[/list]

Yes, the KB Active Sections/Chapters needs to be associated with the Expert Features and is only relevant to experts who are modifying that top level structure.
Most users only modify or create pages lower down in the structure that is not mentioned in that expert advice.
Those users must already know how to navigate the KB and thus have a basic understanding of its structure in order to reach the Page they want to edit and to find the Contribute Your Knowledge chapter. It is rather like your argument that explaining Hyperlinks is unnecessary for such users.

As explained above, I don't think Create And Manage Pages needs an intro to Wiki structure.

According to Tools > Old Revisions you created Creating a New Namespace on 2018/11/28 14:28

Relative v Absolute ~ I hear what you are saying, but as I said in 1. earlier, Create And Manage Pages specifically advises to use Relative Links such as [[One New Page]] and [[.:New Subsection:Index]] to create new pages. Also Links within the Knowledge Base advises a Relative Link of [[Edit Links and Media#Links within the Knowledge Base]] for bookmarking. They make no sense in the context of all the Absolute Links unless we explain to two formats.

The advantages of Relative Links are similar to FH relative v absolute Media File Paths.
If a Page were to use Absolute Namespaces for bookmarking cross-references within its own (or sibling Page) section headings, then as soon as any Namespace higher up the hierarchy was changed all those bookmarks would become broken links.
I know there is a workaround by asking Jane to perform a global edit to fix the broken links, but it does carry some risk.

The icon when hovering over a section Headline, or the asterisk in the Trace, produces an absolute link for pasting into Forum topics as explained in the Forum Usage Guide (4252). Perhaps we need to reiterate that in our guides.

Namespace Conventions
~ Absolute Links are straightforward and as you say, all the tools drive the user that way.
~ Relative Links are much easier for creating new pages, because you just enter the new Page name and don't need to know anything about the structure above ~ simples!
I've realised there are other conventions we have not mentioned:

• The [[One New Page]] and [[.:New Subsection:Index]] links are converted to a Namespace by replacing any sequence of non-alphanumerics with an underscore and converting to lower case, i.e. one_new_page and .:new_subsection:index
• The new page top level headline is automatically created from the link name, i.e. ===== One New Page =====

So perhaps we do need a Namespace Conventions topic that starts with those generic DokuWiki syntax rules, and progresses through our KB stylised Chapter names and structure. But where does it fit amongst the existing topics?

Absolute Crossreferences are straightforward because you only have to hover on a Headline to to see its Namespace and the Link Wizard allows navigation to namespaces whose names match Headlines in most cases.

Shall we agree to call top level sections Chapters?

As explained above, I don't think Create And Manage Pages needs an intro to Wiki structure.

How do you decide where to put your new page if you don't understand that there is a structure, and what it is, and what the terminology is? The 'What Sort of Page' section has been in the outline from the day you created it, and it's hard to cover that if the user doesn't know the basic terminology (namespaces) and some structure info.

I'm coming to the conclusion (like you) that we do need a dedicated page (or set of pages) on the structure of the Knowledgebase -- some of which would ideally be referenced in introductory material about using the Knowledgebase (haven't been able to find it anywhere referenced on the Home page which is I think the only introductory material?) and most of which would be referenced from within the Contribute Your Knowledge structure. So it might have to have a section on its own within Contribute Your Knowledge but be written with the awareness that it will also be used by those who want to navigate the Knowledgebase but not contribute to it. Or maybe just link to the page(s) from Basic Concepts where the word Namespaces is introduced, and then from anywhere else it's necessary prior knowledge (such as when documenting the namespace conventions, or creating pages)?

On the subject of calling the namespace sections 'Chapters' you'd have to rewrite the Knowledge Base Home and possible elsewhere as well. Maybe be disciplined and refer to 'namespace sections' when the subject comes up in the context of the structure of the knowledgebase and then sections thereafter, and 'page sections' when we're talking about page structure and sections thereafter. I don't think there are many of any places where the two concepts have to co-exist?

If we do decide to use a new word, I'm not keen on Chapter. What about Namespace (when it has been suitably introduced) and Page Section/Section -- although we'll have to do some editing elsewhere as already mentioned. (The dokuwiki documentation seems to use namespace as the mot juste). And if not namespaces, Categories?

According to Tools > Old Revisions you created Creating a New Namespace on 2018/11/28 14:28

Yes -- I created a new page to incorporate existing content from contributeyourknowledge:advanceduserguide#new_main_sections|> New Main Sections

Relative versus Absolute: I'm not arguing about the benefits of Relative links -- just warning you that it is so much easier to create Absolute ones that we shouldn't assume people will bother will relative ones.

On a separate topic, I still think the Page on Links and Medis is too long and it could easily be split.

What with festivities and other commitments I haven't been able to consider this and won't be able to pick it up until February - Sorry!

No problem -- I'll come back when you do.

Mike, are we yet able to come back and complete this?

Yes, things are easier my end now, except that I am waiting for a minor cataract related operation in next few weeks to cure my currently blurred vision that makes detailed PC work tediously awkward.
I was also holding back, as you were heavily involved in A simple to-do list (16751).

Let me remind myself of the Namespace issues and come up with some suggestions.

I know (from relatives) how cataracts can impact, so will back off until you're ready. Lots of stuff to do on Simple To-Do Lists (and plugins) but when we get people willing to contribute to the KnowledgeBase we should strike while the iron is hot?

Mike Tate,
are we yet in a position to move forward on this? I'd hate to see the work we've done so far wasted.

Yes, sorry, it is one of those tasks that I knew needed addressing, but kept kicking into the long grass.
I have spent a little time reviewing where we got to, and the issues with namespaces.

So, we are discussing where to introduce general Wiki and specific KB Namespace concepts...

1. contributeyourknowledge:edit_existing_pages|> Contribute Your Knowledge ~ Edit Existing Pages in Edit and Save a Page says "Navigate to the Knowledge Base Wiki page you wish to edit." but otherwise says nothing about Namespace concepts.
2. contributeyourknowledge:edit_links_and_media|> Contribute Your Knowledge ~ Edit Links and Media introduces Namespace concepts & links.
   contributeyourknowledge:create_and_manage_pages|> Contribute Your Knowledge ~ Create And Manage Pages manages Namespace internal links.

I think we are proposing a Contribute Your Knowledge ~ Namespace Concepts page that sits between 1. and 2. above (or perhaps even before 1.) and brings together the following:

• contributeyourknowledge:create_and_manage_pages#introduction|> Introduction to both Wiki and KB concepts.
• contributeyourknowledge:edit_links_and_media#namespace_conventions|> Namespace Conventions for Wiki links in general.
• Namespace Conventions from my posting on Mon 17th Dec 2018 16:03.
• contributeyourknowledge:knowledgebaseeditingreference:activesections|> Knowledge Base Editing ~ Active Sections of our KB namespaces.
• Anything else?

All other pages should then be able to refer to that Contribute Your Knowledge ~ Namespace Concepts page.

I wonder if our pieces of long grass are near each other....

I agree that's where we are, and the right way forward. Do you want to create the new page? Or I can do it if you prefer.

I think there is a lot of long grass these days, fertilised by BREXIT

I will create the new page and start populating it with topics.
Does it need to sit before or between 1. and 2. listed earlier?

I thunk between -- people editing an existing page don't need to know about it unless they're introducing links?