Page 1 of 5

Contribute Your Knowledge Improvements

Posted: 12 Nov 2018 15:24
by tatewise
This thread is derived from discussions in Draft pages and Downloads in Knowledge Base (16371).

There is much advice in Knowledge Base > Contribute Your Knowledge and that refers to for example that explains that topic in more detail with various shortcut options.

Re: Contribute Your Knowledge Improvements

Posted: 13 Nov 2018 10:26
by ColeValleyGirl
Information about the Pushfile plugin is only available if you know you need to look for it.

How might I have known that? Well, like a good little girl, I started at : Knowledge Base > Contribute Your Knowledge.

Nope, I don't need the Beginners Guide -- it will only tell me the basics of page formatting, and I don't need to be told about that.

Nope, I don't need the Intermediate Guide -- I'm not going to create any clickable hyper-links from one page to another. Quick check just in case -- no, it doesn't mention files, just web pages etc.

Gosh, is including a Downloadable file really an Advanced topic? Maybe it comes under 'the use of images' or maybe 'specialised processing tool'? Seems odd, as it's the kind of thing that people do all over the web every day, but hey-ho -- let's go and look.

Ah -- Inserting images mentions a button to Add Images and other files. And that button lets me upload files, put them in a 'namespace' and link to them; and the links function as download links. Hey presto. Job done.

No need to look at the Page Formatting Syntax Reference -- nothing I'm doing is rocket science, and anyway it only covers the 'features described in the three User guides' I've already glanced through.

If I wanted to add a Download Link to the Downloads and Links Page (which I don't), I (just) might have found my way to the Download Links advice -- although the Add a Downloadable File page provides a form to fill in, mentions the Add Images and other files button for managing media... and doesn't mention that the Download Links advice is applicable elsewhere, so I probably wouldn't have bothered or needed to read it if all I was doing was adding a Download Link. And anyway, it's a completely different page address from Pushfile plugin although the content is (almost) identical.

On the plus side, I now definitely understand why so few people bother trying to edit the wiki. I'd have more fun with Alice down the Rabbit Hole.

Re: Contribute Your Knowledge Improvements

Posted: 13 Nov 2018 11:11
by tatewise
Sorry, you had difficulties with the Knowledge Base > Contribute Your Knowledge pages.
It is difficult for me to appreciate the first impressions of other users faced with understanding the features from scratch.
So, any advice on how it could be improved would be welcomed.

I maintain that amending existing textual pages is relatively easy, and not significantly different from posting in the Forums.
But the Wiki features are quite extensive and the advice tries to introduce the basics separately from advanced features.

I accept the wording against Knowledge Base > Contribute Your Knowledge ~ Page Formatting Syntax Reference is misleading, as it includes a few features not described in the other three User Guides, and unfortunately in the current context Knowledge Base > Download Links is one of them, and replicates the Knowledge Base > Pushfile Plugin advice.

I will investigate how best to rectify that misleading advice, that I agree did not help you.

Jane & I introduced the Knowledge Base > Add a Downloadable File forms, which we thought would satisfy most users. As far as I am aware you are the first who needs to download files independently from the Knowledge Base > Downloads and Links section.

Re: Contribute Your Knowledge Improvements

Posted: 13 Nov 2018 11:51
by ColeValleyGirl

I agree -- maintaining basic textual pages (which I would argue includes downloadable links) ought to be relatively easy, but -- as I've found out -- there are some gotchas (and I anticipate I haven't tripped over all of them yet).

I will think whether there are any suggestions I can make about the Contribute Your Knowledge Pages -- some of the problems might be structural and so very hard to fix; others could just be wording tweaks to make it clear where/when it's advisable to read specific sections of the advice. And of course we're struggling with the ongoing Search challenge -- try searching for Downloads, for example -- you get loads of hits for downloadable items, but if the Pushfile plugin is mentioned I can't see it.

I think one general comment I would make is that the pages vary between treating the reader as if they know nothing (when I'd suggest that anyone who is considering editing the wiki will be bringing to it a degree of experience elsewhere on the Web), or assuming that they've read every little piece of documentation (which is unrealistic).

Most people (like me) will have a specific task in mind when they go looking through the wiki documentation, rather than wanting to spend some hours getting increasingly tangled up in a rats nest, so perhaps the structure ought to be considered with that expectation. Yes, there's a place for 'a manual' to be read cover to cover, but that 'entry' page needs to offer that as an option and not the only way in (in the same way as you can read a Help file from cover to cover, or jump straight in at the one section you care about). But that's the sort of very difficult structural change I'm thinking of.

On the subject of Rats Nests, I still can't work out how to get back simply to where I started in a documentation 'tree' -- I'm looking at the Home page now and the Trace is saying "How to Add Downloads and Links / Downloads and Links ~ Diagram Icons / About Downloads and Links" -- but I haven't visited the Diagram Icons page on my route through! And if I open 'my page' in a new browser window, the Trace says: How to Add Downloads and Links / Downloads and Links ~ Diagram Icons / About Downloads and Links/ Knowledge Base Home *. Which leaves me shaking my head in total bewilderment.

Re: Contribute Your Knowledge Improvements

Posted: 13 Nov 2018 12:20
by tatewise
I'm not sure downloadable links is that basic, and is only one aspect of all the hyper-link features. Anyway, we thought we had catered for the majority of downloads via the Knowledge Base > Add a Downloadable File method.

I've made some simple changes to the Knowledge Base > Add a Downloadable File and Knowledge Base > Contribute Your Knowledge sections to make download of data files more visible. Any more specific advice about improvements is welcomed. The difficulty I find is double guessing what experience other users bring to the table (c.f. postings in Forums with minimal information), and the nature of the task or knowledge they want to document. Yes, you have a particular task, but would other users have a different task, and would that need a different structural change?

The Knowledge Base Trace persists throughout your FHUG session.
So you would have visited those pages that are listed sometime earlier today.
It is a bit like the Go Back/Forward white arrow buttons in FH.

Re: Contribute Your Knowledge Improvements

Posted: 13 Nov 2018 12:46
by ColeValleyGirl
I'm still confused about the Trace. I've just opened the Knowledge Base in a completely separate browser, on the Home page, and it's showing the Trace as Downloads.... When I have some time, I'll investigate further.

The simple changes you've made are good, but I still think there's a systematic problem -- you can't find what you're looking for unless you're willing to wade through pages of irrelevance to a specific task, because the fundamental structure doesn't recognise task-orientation. The "manual" approach is necessary but it isn't sufficient.

Re: Contribute Your Knowledge Improvements

Posted: 13 Nov 2018 13:06
by tatewise
I usually use Firefox as my default browser.
I've just used Google Chrome to access the [kb]|[/kb] and there was no Trace, even if I logged into the Forums.
However, if I open another browser page (not tab) instance of Firefox then the Trace is preserved.
That is similar to preserved logins to such as Ancestry or FindMyPast that synch across multiple instances of the same browser, but NOT to different browser products. Jane might give a fuller explanation.

Please give me some more clues regarding a task-oriented structure for the Knowledge Base > Contribute Your Knowledge section, perhaps some examples of the page topics you think are required.

Re: Contribute Your Knowledge Improvements

Posted: 13 Nov 2018 13:39
by ColeValleyGirl
I'll try and make some time later in the week to come up with a task-oriented structure, but it would turn the existing structure on its head -- instead of Beginners Guide, Intermediate Guide, Advance Guide, Really Super-Advanced stuff, you'd have bite-size chunks (even if they're implemented as anchors on longer (existing) pages). Something that allows a user of whatever experience level to quickly find the stuff they want to do. Here's an incomplete example -- I've but in some bolded descriptors but wouldn't envisage them appearing.

Nuts and Bolts
  • Signing up to edit
  • Understanding the Knowledge Base structure (seems to be scattered everywhere in the documentation; the topic will need to be further broken down -- and this piece is crying out for diagrams)
Routine tasks -- this will probably cover a lot of what many users want to achieve
  • Adding Downloads and Links to the download section (which is not the same as putting them in an 'ordinary' page as it uses the form.)
  • Adding a Member website.
Editing and creating pages
  • Editing a Page (with visible and directly accessible subsections on formatting, adding images, adding links, link shortcodes, adding downloads, footnotes, special characters, etc.)
  • Creating a New Page (currently hidden unless you happen to look in the intermediate guide)
  • Renaming a Page
  • Deleting a Page
  • Managing files
  • Something about the links that **must** be made between pages for the Wiki structure to function?
  • Something about scheduled/one-off maintenanc eoperations that need to be run for some changes to take effect
Reference material
  • Detailed Reference manuals
Tips and Tricks (techniques that might be useful but not immediately apparent

  • 'Draft' pages
  • 'Hidden' downloads

Re: Contribute Your Knowledge Improvements

Posted: 14 Nov 2018 15:31
by tatewise
It may not be too difficult to achieve the structure you have proposed from existing sections, but does anyone else have an opinion?

Knowledge Base > Contribute Your Knowledge ~ Beginners User Guide
Covers much of the Nuts and Bolts, Routine tasks, and Editing pages.

Knowledge Base > Contribute Your Knowledge ~ Knowledge Base Editing Reference has :-
Knowledge Base > Knowledge Base Editing ~ Active Sections covers Knowledge Base structure.
Knowledge Base > Knowledge Base Editing ~ Create/Delete Pages covers Page operations.
Knowledge Base > Knowledge Base Editing ~ Link Options covers most Link options.

All the other existing guides can form the Reference material.

There may a be few gaps that need plugging, including "scheduled/one-off maintenance operations" advice, and Tips and Tricks will be a useful addition.

Re: Contribute Your Knowledge Improvements

Posted: 14 Nov 2018 16:04
by ColeValleyGirl
From experience today, I think we should also cover (within managing files): deleting media; updating media; renaming media...

Which I understood after I found my way to dokuwiki documentation.

Re: Contribute Your Knowledge Improvements

Posted: 14 Nov 2018 16:29
by tatewise
Yes, may need something, but I am wary of repeating too much advice that is already well covered in the dokuwiki guides.
There are already several references to the

The complication is that a large proportion of editing the [kb]|[/kb] is standard dokuwiki with a number of standard macros, but Jane has added custom macros specifically for FHUG and it all operates within our FHUG namespace. So balancing the standard and custom aspects is tricky. It is somewhat like FH itself that has much Help for the standard features, and the [kb]|[/kb] covers a lot of customisation features.

Re: Contribute Your Knowledge Improvements

Posted: 14 Nov 2018 16:31
by ColeValleyGirl
Mike, at least we should provide task-based pointers to the relevant dokuwiki advice instead of expecting people to plough the scads of text. -- we know where the info is; why should anyone else have to trawl for it?

I'm not arguing to re-document stuff, just signpost it usefully.

Re: Contribute Your Knowledge Improvements

Posted: 14 Nov 2018 16:40
by tatewise
It might help to know why you could not find the cross-references that exist with the advice about linking images. May be they are not everywhere they need to be.

Re: Contribute Your Knowledge Improvements

Posted: 14 Nov 2018 17:07
by ColeValleyGirl
Mike, go to Contribute Your Knowledge.

Pretend you know nothing.

How do you delete a Media file?

Re: Contribute Your Knowledge Improvements

Posted: 14 Nov 2018 22:54
by tatewise
OK, scanning through the initial page, the Advanced User Guide says "it explains how to: ... Display images,"
So assuming that might be a good place to look, in the Advanced User Guide I find the Images and Downloads section.
From there I might go several possible ways.
  1. Click the quickbutton link and then Media Selection link to reach The Media Manager page
  2. Click the media_manager link to reach The Media Manager page
  3. Click the Include Images link where a couple of Images button links look promising.
    They lead to Image and Media Handling with Removing Media link on the right.
    That says "Files can be deleted with the garbage can icon" and the deleting media files link leads to some similar advice with a media manager popup link to reach The Media Manager page
  4. I might notice that Page Formatting Syntax Reference covers the above, and then follow Page Formatting ~ Image Files link to the same point as 3. above.
All above paths lead to the The Media Manager page, where a scroll down shows Delete the file garbage can icon.

But users don't start by deleting Media files; they start by uploading Media as advised in the sections identified above.
If the user Uploads via Add images and other files quick button, the garbage can Delete button is fairly obvious against each file.
Alternatively, the Tools > Media Manager window has a fairly obvious Delete button on the right-hand View tab.

As you said earlier, it should be assumed that users attempting such tasks are reasonably experienced and computer literate.
It does not take much investigation of the Media Manager windows to find the Delete options.

Re: Contribute Your Knowledge Improvements

Posted: 15 Nov 2018 09:50
by ColeValleyGirl
Mike, users can add files (and do loads of other things) without registering any details of the interface other than the one that matters to them at the time.

However, I'm sensing you don't think it's at all worthwhile to make things easier for people who don't work/think the same way that you do -- whereas I can't understand why we wouldn't want to put links through from the Contribute Your Knowledge page to instructions the tasks that ought to be simple as well as preserving the manual-based approach that you prefer.

But let's try one last time before I give up.

The simplest way to 'Contribute their knowledge' for any user is to add a link to their own Website or to a Download. But there's nothing on the current Contribute your Knowledge page that gives them a clue how to do it. You, no doubt, will say: well, they ought to go the page of existing Downloads and Links because that is the way your (some people's) mind works.

I say it ought to be accessible as well from the Contribute your Knowledge Page. No extra pages needed, just some links to speed up the Navigation/provide a better 'Information Scent' (the confidence that good navigation will give a user that they're going to find what they're looking for at the end of a journey through the site).

Re: Contribute Your Knowledge Improvements

Posted: 15 Nov 2018 11:07
by tatewise
Sorry if I give that impression - it is not intended - but I do use an interrogational style to try and understand your perspective.

You must have overlooked the Knowledge Base > Beginners User Guide > Quick Start Steps that explains about adding websites and downloads.

With reference back to your Nuts and Bolts, etc, section...
Do you still think Knowledge Base structure should be introduced that early?
i.e. Knowledge Base > Knowledge Base Editing ~ Active Sections
Or is your concept of Knowledge Base structure something different?
My feeling is that it is not needed until the Editing and creating pages section.

To get down to brass tacks, could you propose an actual Contribute Your Knowledge page structure.
i.e. Actual section Headline Level 2 titles, with Headline Level 3 sub-headings &/or links to pages.
Include a brief summary of what topics each section covers.
You can edit the actual Knowledge Base > Contribute Your Knowledge page if you wish, but do so near the bottom just above the Related Pages section.

We could make much more use of the Changes, FAQs, Titles & Index cross-references:
Knowledge Base > Contribute Your Knowledge FAQs
Knowledge Base > Contribute Your Knowledge Alphabetic Titles
Knowledge Base > Contribute Your Knowledge Alphabetic Index

Re: Contribute Your Knowledge Improvements

Posted: 15 Nov 2018 15:57
by ColeValleyGirl
Mike, yes I overlooked the Quick Start guide because it's hidden inside the beginner's guide that supposedly only talks about formatting...

Re knowledge base structure, I think some of the basics is needed early on -- the fact that *everything* is a page, for example -- but other stuff can wait.

I'll try and do a example page over the next few days -- as a draft (I'll post the link here.)

Re: Contribute Your Knowledge Improvements

Posted: 15 Nov 2018 17:52
by ColeValleyGirl
Mike, very much a work in progress but see ... e_approach

Re: Contribute Your Knowledge Improvements

Posted: 17 Nov 2018 07:46
by David2416
So the target audience is: users first attempting to add knowledge and experienced users needing a reference manual? How about a glossary - namespace might be unfamiliar to some.

Is there a need for review before public posting?

Re: Contribute Your Knowledge Improvements

Posted: 17 Nov 2018 09:36
by ColeValleyGirl
I've added Glossary to terms (placeholder only) to my suggesting Alternative starting page -- I agree that some terms like namespace need introducing at the right point/in the right way to relative newcomers, whereas experts here or elsewhere may be very familiar with them.

Re the audience, I'm aiming at something that is useful for everyone, which recognising that there are different levels of experience and different ways of absorbing information, so we need pointers to bite-sized chunks both for beginners and for people who are focussed on accomplishing a specific task, and more discursive material for people who want to understand everything and/or the really specialised stuff.

Re review before pubic posting, we haven't had it to date and I wouldn't want to see it introduced now.

Re: Contribute Your Knowledge Improvements

Posted: 17 Nov 2018 10:38
by tatewise
Welcome on board David. It will be great if all three of us can pool our ideas.

I have added an explanation of Namespace to the Knowledge Base > Simple Concepts (assuming it will become contributeyourknowledge:index although at present it is actually contributeyourknowledge:alternative_approach).

I agree that postings don't need formal reviews.
The Knowledge Base > Knowledge Base Home > Latest Updates to the Knowledge Base lists all recent edits and lists more detailed changes; keep clicking less recent >> and it goes back about a week.
So anyone can keep any eye on changes plus if any page is in error it can be corrected or easily reverted to a previous version.

BTW: Those lists reveal that the Research Task Manager that Helen was working on has all been removed.

Re: Contribute Your Knowledge Improvements

Posted: 17 Nov 2018 11:06
by ColeValleyGirl
Mike, that's because it will spring back to life this weekend as a Research Planner plugin (better title) --- just waiting for my worst critic to review the Help file...

Re: Contribute Your Knowledge Improvements

Posted: 17 Nov 2018 12:23
by tatewise
I have migrated some components from Knowledge Base > Contribute Your Knowledge > Introduction and Knowledge Base > Quick Start Steps to supplement the Knowledge Base > Alternative Approach Introduction, Basic Concepts, Getting Started & Editing Pages sections.

Also all the notes that were red hyperlinks are now Fix Me! italic notes.

Is this heading in the right direction?

Re: Contribute Your Knowledge Improvements

Posted: 17 Nov 2018 14:49
by ColeValleyGirl
Mike, is it a convention of the wiki that we have that dense section of links at the top before we get to the useful (and more welcoming) stuff? Or can we move it elsewhere on the page (as it's not going to be the fist thing -- or even maybe the last thing that people want to see? If we get the contents of that first page right, the 'About' and 'FAQS' will be redundant, and the Alphabetic titles and Index could go into the final section (Reference material).

I'd also quite like to lose the 'wonderful world of wiki' bit -- for new users it's patronising, and for experienced users it's pointless.