Web based family history software

Question Help text issues - urgent discussion needed

  • kiwi
  • Topic Author
  • Offline
  • Platinum Member
  • Platinum Member
More
13 years 10 months ago #1 by kiwi
The 're-branding' excercise is now 99% complete. The major problem remaining is the Help text, especially the "Help for this page" items that are very long. They present a number of issues:
  1. their length means they do not fit well into launchpad's translation tool (greg has raised a launchpad bug for this)
  2. they are FULL of $factarray and $pgv_lang references no longer relevant to webtrees
  3. They really need completely re-writing. They have too much technical 'jargon', and generally don't work well fro webtrees

Discussing this offline Greg and I had a couple of ideas. Our conversations are below, so we can get your views on them...

kiwi - Well, I had a look - and the whole thing is a mess (as you say). It looks to me like a major re-write of Help is needed, at the very least for the "Help for this page" long items.

fisharebest - FYI, I have just raised a bug report at launchpad regarding long items. If you click the "copy" icon, to copy the text from "en" to "en_GB", it only copies the first 4096 chars.

These long texts are a pain to translate, as they do not fit into the edit box. We should limit individual items to single paragraphs.

We should also remove unnecessary HTML markup. e.g. this recent item

Here is a short description of each of the blocks you can place on the Welcome or My Page.<br /><table border='1' align='center'><tr><td class='list_value'><b>Name</b></td><td
class='list_value'><b>Description</b></td></tr></table>

should be three separate items

1) Here is a short description of each of the blocks you can place on the Welcome or My Page.
2) Name
3) Description

with no HTML.

We need to make much better use of place holders, e.g.

"click on the <b>&gt;</b> button"

versus

"click %s", '<input type="button" value="&gt;">'

Easier to translate, and no retranslation needed if we replace the ">"
with a different icon.

> There are loads of them FULL of comments about $factarray[] and $pgv_lang[] variables and similar issues. Many of them, for me at least, will need testing before I can write anything meaningful.

They also seem to to be way out of scope. e.g. the HTML editing instructions do not really need to explain about html entities, CSS, and that your opening and closing tags must match....

> I'm inclined to raise a BluePrint for this, plus a forum post (in the public area), asking for volunteers to help. It's a BIG job, but one that needs doing, and soon. I know 'pcfusebox' had a go at this area, but that was early on before many of us had any real understanding of how gettext would work in these places.
>
> Is that a good idea in your view?

I want to avoid the situation where text is continually refined. Each changed comma means a lot of work for all the translators.

I guess we need to start a process that leads to a set of guidelines for writing help text.
If we do this using a few real-world examples, then all well and good.

As a starting point, I guess we need to know how many "page help" and "major topic area help" (e.g. what is a gedcom file) articles are there?

Should the help text contain links to wiki pages?

kiwi - Or should the Help text BE links to WIKI pages, at least for the "Help for this page" ones? Much easier to maintain there, and I'm sure we can link to other language versions.

fisharebest - It would certainly solve many problems, be easier to contribute, add examples, etc.

It would be simple enough to generate links containing the language code and the help-text-reference/page. e.g.

wiki.webtrees.net/en/module_admin.php

There are obviously downsides.

1) Help text for version 1.0.0 may be different to version 2.0.0

2) No mechanism for identifying that updates to the help for one language need propogating to other languages.

Instead of directing directly to the wiki, we could have a simple help text built in to the system, with a reference to the wiki. e.g.

This page allows you to edit your foo/bar settings. etc. etc. etc.

A more details explaination and further examples are available at wiki.webtrees.net/en/Foo_and_Bar_Settings

This allows the wiki titles to be translated.

It's certainly worthy of further discussion.

kiwi - Yes, I like the idea of a brief explanation plus a link to the WIKI. That works well for off-line usage of webtrees as well.

I'll copy these discussions to a forum post, to see what others think.

Please Log in or Create an account to join the conversation.

More
13 years 9 months ago #2 by WGroleau
Replied by WGroleau on topic Re:Help text issues - urgent discussion needed
Can someone quote part of a particularly long text, enough for me to search for it in the translation interface?

Thanks

--
Wes Groleau
UniGen.us/

Please Log in or Create an account to join the conversation.

More
13 years 9 months ago #3 by fisharebest
Replied by fisharebest on topic Re:Help text issues - urgent discussion needed
There is one referenced in my bug report: bugs.launchpad.net/rosetta/+bug/583566

Please don't correct it - I'm leaving it "broken" as an example for the bug report.

Greg Roach - greg@subaqua.co.uk - @fisharebest@phpc.social - fisharebest.webtrees.net

Please Log in or Create an account to join the conversation.

Powered by Kunena Forum
}