Help? ‘Grande catastrophe!’

Thu, 18 Jul 2024 14:26:30 +0200

adminsforum@hubzilla.org

Der Pepe (Hubzilla) wrote the following post Thu, 18 Jul 2024 14:26:48 +0200

Help? ‘Grande catastrophe!’

Help? ‘Grande catastrophe!’

I don't know since when, but the help app has become completely unusable. At least if you switch to a language other than ‘en’.

The localised version of ‘About’ is then displayed. In ‘de’ the menu / table of contents in the left sidebar is empty. For ‘fr’ it is available. In any case, except for the language setting ‘en’, the links of the TOC lead to nothing (page not found) because they refer to ‘/help/...’ instead of ‘/help/en/...’ or ‘/help/#selected language#/’.

How can this be ‘repaired’ so that the help system refers to the default English language for help pages that have not been translated? As it is now, it is not usable (at least not for inexperienced users).

show all 21 comments

Thu, 18 Jul 2024 16:36:18 +0200

Grouchy

grouchy@hub.grouchysysadmin.com

Same here. Good catch.

Fri, 19 Jul 2024 18:43:42 +0200

Harald Eilertsen

harald@hub.volse.no

That could be my fault. I did some pretty massive changes to the help system a while ago, but thought it had been working well after that. Now I see the same as you do, so not sure if anything has happened in the mean time, or what's going on. I'll have a look at it again once I'm back from vacation next week!

Sun, 21 Jul 2024 13:11:57 +0200

citc

citc@zotum.net

More robust tests are necessary before changes

Sun, 21 Jul 2024 14:12:29 +0200

_jayrope

jrp@hub.kliklak.net

@Harald Eilertsen You're da best. It's great that you have started that change, and of course there's always bumps on the way out. Thanks for doing this.

Sun, 21 Jul 2024 18:22:10 +0200

Harald Eilertsen

harald@hub.volse.no

@citc Agreed!! Which is why I added a lot of tests to this part of the code too. There's still a long way to go, but from no tests at all we're slowly getting to a better state.

Mon, 22 Jul 2024 21:16:34 +0200

Harald Eilertsen

harald@hub.volse.no

@Der Pepe (Hubzilla)

The localised version of ‘About’ is then displayed. In ‘de’ the menu / table of contents in the left sidebar is empty. For ‘fr’ it is available. In any case, except for the language setting ‘en’, the links of the TOC lead to nothing (page not found) because they refer to ‘/help/...’ instead of ‘/help/en/...’ or ‘/help/#selected language#/’.

There's several issues here, I'll try to unwrap them and discuss them one by one:

If a help topic does not exist in the selected locale, the localized about page is shown instead.
The table of contents does not exist in all locales.
The links in the TOC is not correct for locales other than English.

I don't believe the first point is correct. The about page will be shown if no specific help topic is specified. (I found a bug in this case, if only the language is specified in the URL, but no topic, the request would fail with a 500 status. I'll submit a fix for that.) If a topic is not found, you should now get a page not found screen, whereas previously it would try to fall back to the English topic, which didn't quite work.

The second point is somewhat as designed, but I'd like to find a better solution for this.

The TOC file now needs to be in the directory of the locale requested. We can copy the English TOC file to the locales missing one, but in itself that would not make the situation much better. The various locales does not have all the same topics as the English one, and in some cases (like for German) the structure of the file tree does not even correspond to the same layout as English. Having separate TOC files for each locale would also solve issue 3.

In addition there's a potential mismatch between the channels selected locale and the help locale, and that the help system does not support all the same locales as the rest of the server. I need more tests to cover all these cases as well.

Tbh, the Help system still needs a lot of work! But more than that I think we need to decide how we want it to work.

I see a few alternatives:

The help for each locale is completely independent, and has it's own structure and TOC file.
The help for each locale is a sparse mirror of the English help, keeping the same structure and file names, but missing topics result in a page not found.
Same as 2, but we try to fall back to the English file if we could not find the topic in the selected locale.
Same as 2, but with the page not found screen pointing to the requested topic in other languages if it exists.

Mon, 22 Jul 2024 22:49:43 +0200

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

Thank you, that explains a lot. I had already thought about successively translating the existing help into German.

A lot of work, especially because parts of the documentation are outdated (no longer valid for the current version).

I've been looking at the structure of the help these days and your comments here have confirmed some of my thoughts.

So... I'll get to work on the translation (without pressure, stress and rushing).

I have nothing else to do. 😉😂 But this way I can also give a little back to Hubzilla.

BTW: I have also started to translate the articles of my Hubzilla KnowledgeDB ‘bit by bit’ into English. This is much harder work because1. English is not my mother tongue (but German) and 2. I am much more busy with Hungarian in everyday life, the language spoken in my new home country (living in the south of Hungary for over 12 years). Anyway... most of the help is too technical and abstract for beginners... that's why my wiki is aimed more at beginners... and there are many of them who understand English better than German. So I do that on the side too.

@Harald Eilertsen

Tue, 23 Jul 2024 10:09:13 +0200

Harald Eilertsen

harald@hub.volse.no

@Der Pepe (Hubzilla) I'm not sure I see that much value in a literal translation of the existing help docs. As you say, they're too technical and not up to date – and it's a lot of work to translate it all!

I'm hoping we can use this opportunity to shape the help docs (also for English) into a more usable and user focused state. And also to make it easier for translators to keep their translations up to date. I think the Hubzilla KnowledgeDB is a way better starting point than the current help docs. (Really nice work!)

I'm open to suggestions, and happy to help with getting the changes into the repo if you need!

Tue, 23 Jul 2024 10:35:27 +0200 last edited: Tue, 23 Jul 2024 10:36:23 +0200

Harald Eilertsen

harald@hub.volse.no

There's one other issue with the current implementation of the help system I'd like to get some opinions about:

Help docs are organized in topics that are access via a URL like /help/lang/section/topic. This corresponds to the file doc/lang/section/topic.{bb,md,html} under the Hubzilla root directory on the server. Fairly easy and straight forward.

However, the same content is also available under /help/section/topic. I.e. without specifying the language in the URL. This uses the language that the channel is currently set to use to find the file in the correct locale. Also fairly easy and straight forward.

What's a bit confusing is the two together.

Do we really need to support both URL schemes? Personally I think I would favour the latter one. Just use the language of the channel and try to find the topic there. This way the URL to a help topic will be the same regardless of language settings.

We will need to handle docs missing from the locale in a better way, but that's a problem we can solve.

The one disadvantage I see is that it would be difficult to link to a topic in a specific language. I'm not sure it that's ever a useful thing, but if you think it is – let me know!

Please let me know what you think!

Tue, 23 Jul 2024 11:07:47 +0200

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

@Harald Eilertsen Just a quick comment on your first point: Yes, it would be really good to reorganise and redesign the help section in terms of content and topics. Especially the user guide and tutorials section. I can certainly take over some of the content from my wiki, but I would have to make sure that I get rid of all the graphics and describe it as text instead.

Tue, 23 Jul 2024 11:16:00 +0200

Harald Eilertsen

harald@hub.volse.no

@Der Pepe (Hubzilla) We can (and probably should) add more illustrations to the help pages. I have tried adding some to the doc on tags and mentions, when I updated that part. There's probably still room for improvement, but it's a start :)

Tue, 23 Jul 2024 11:51:46 +0200

Mario Vavti

mario@hub.somaton.com

I think it is questionable to support multiple docs languages and keep them in sync. It would be great of course if it would work. In reality not even the english content is uptodate :thinking_face:

Tue, 23 Jul 2024 12:21:53 +0200

Harald Eilertsen

harald@hub.volse.no

@Mario Vavti With the current resources I think you're right. If we can gracefully fall back to the English docs when no translation exists, it should be possible to keep at least the most important docs translated.

Then again, we will reduce complexity that may not have much value if we just say docs are in English.

Tue, 23 Jul 2024 12:48:59 +0200

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

I think the idea of a fallback to the English-language help if entries are not available in the localised version is a very good one. This also takes the pressure off those who set to work translating the help into their own native language. The help then simply works, even if only a few entries are translated... only the English version is shown when you make the appropriate selection.

When I approach the German-language help, I would first orientate myself on the structure of the English help (TOC) and then work my way through from top to bottom and add chapters if necessary.

That brings me straight to the first entry, tutorials, ‘Personal Channel’, which needs a rewrite... so I'll be writing it from scratch. The current version is pretty outdated... starting with the channel roles, which have changed quite a bit. A beginner who opens the tutorial to create their first channel will fail at this point because the old roles, as described there, no longer exist (this also applies to the chapter ‘Channel Permission Roles’ in the User Guide).

But no-one has claimed that the help system could be redesigned ‘in passing’. There is certainly a lot of work involved. That's why I'm simply starting on the basis of the existing help.

Tue, 23 Jul 2024 13:22:59 +0200

Harald Eilertsen

harald@hub.volse.no

@Der Pepe (Hubzilla)

I think the idea of a fallback to the English-language help if entries are not available in the localised version is a very good one.

Great, I'll implement this as a starting point.

I'm also removing the independent language selector in the help pages, so we'll always assume the language of the channel is the preferred language. If it's not available we'll fall back to the English page, and add a notice that it is not yet translated to the preferred language.

Wed, 24 Jul 2024 09:30:59 +0200

RockyIII

rocky3@im.allmendenetz.de

@Harald Eilertsen

I'm also removing the independent language selector in the help pages, so we'll always assume the language of the channel is the preferred language. If it'

That way a help page URLwill also work as a link :-)

Wed, 24 Jul 2024 12:15:11 +0200

Harald Eilertsen

harald@hub.volse.no

I submitted a merge request with the requested changes here: https://framagit.org/hubzilla/core/-/merge_requests/2140

Mon, 29 Jul 2024 15:41:57 +0200

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

I'm thinking about rebuilding the Hubzilla help centre: Reorganisation of the Hubzilla Help - Neuaufbau der Hubzilla Hilfe

Mon, 29 Jul 2024 22:22:17 +0200

Jupiter Rowland

jupiter_rowland@hub.netzgemeinde.eu

@Der Pepe (Hubzilla) It's better to rewrite most of the English documentation or at least give it a thorough.

I thought it couldn't get any worse when I found help pages that still mention tech levels... until I found help pages that still talk about the Red Matrix. I wish I was joking.

Also, people need a manual. With how-tos, ideally. Most of Hubzilla's help reads like a technical specification, however.

Tue, 30 Jul 2024 11:20:55 +0200

od@zotum.net

Contribution made to sections 'accounts', 'nomadic identity'', 'channel permission roles', 'web access'.

Sun, 29 Sep 2024 15:04:39 +0200

Harald Eilertsen

harald@hub.volse.no

I thought I had fixed this issue, but it seems I forgot a bit. Anyways, submitted a new merge request now that should make the help work also for non-english users.

Sorry about all the chaos!