Forum > Documentation (Maintaining -)

Wiki Article

<< < (9/9)

Nimral:

--- Quote from: dbannon on February 03, 2022, 12:25:49 am ---Some time ago we had a panel game here on TV where they were doing this and the contestants had to try and figure what the (very short) document said originally, sounds like the translation systems work a lot better now.

--- End quote ---

I think they indeed got far better. Back in the days of Microsoft's old MSDN, machine translations were dreaded in Germany, because the translations were barely making any sense, unless one got used to kind of "translator slang" and got able to rearrange the translated contents in his mind while reading. Not to mention the numerous errors sending one off in a completely wrong direction, wasting countless hours of labour time. Usually they were not caused by the translation but by glitches in the English original. My impression was that the translators had no clue what they were translating.

I was especially pleased to see that Google Translate picked up that the page I tested with was about computing, and thus did no longer translate "Thread" to "Gewinde", which is the German word for what you cut on bolts to become screws. And as I have tried on the page about daemons and services, putting "notranslate" tags around the code section keeps that from beeing translated, and I was prepared to do it for technical terms too, it was a relief to see that the translator did that by itself.

I did then, unfortunately, run into a problem providing the source code in one contiguous file (not having to provide .lfm files), I changed the code to run without, but that did, in my opinion, screw up the whole page totally. Another "enforced" mistake was to post the final thing, which got rather long because I had to add significant code to get Windows and Linux work the exactly same way. Furthermore the main part doesn't match the instructiopns on how to start a daemon project inbitially given any more, since I had to switch from GUI components to programmed initialisaton. Now I have reached my "one running out of the box" goal, but the page turned out ugly and barely readable.

I hope Davo's sample code repo gains momentum soon, I will then happily revert all that stuff, put only snippets into the wiki, move the extensive comments into the text body, and provide a link to the repo right at the beginning for those programmers who do read code easier than written text.

After having been really frustrated by the materials provided by the Lazarus community, I do see thing unfold into a very pleasant direction, and I am very pleased to be a part of it :-)

Armin.

Nimral:
Btw ... anyone here who is willing to try the automated Translations for Slavic or Nordish languages? I suspect that, because of the common roots of English and German, automated franslations between them and other "Roman" influenced languages like Italien or Spanish might work better than other languages, but I speak only English and German, so I cannot check myself.

Nimral:

--- Quote from: dbannon on February 03, 2022, 12:25:49 am ---Yes, I think you should. Make a German version of it, don't manually edit anything so we can see it warts and all. I'll then take that German copy and convert it back (but not publish on the wiki as its redundant) just to see how readable it is.

--- End quote ---

Ok, here we go.


--- Quote ---Lazarus Examples Window


This wiki page is an attempt to capture people's thoughts wrt replacing the existing Examples Window in the Lazarus IDE.

    Its based on this forum thread - https://forum.lazarus.freepascal.org/index.php/topic,57680.0.html
    Its (hopefully only initially) one person's view of the discussion.
    It has a limited life, no need for it to exist after the matter is resolved (or abandoned).


content

    1 Why is there a problem?
    2 What should the user experience be like ?
    3 How do we achieve this?
    4 methodology
        4.1 Examples Remain in Distribution.
        4.2 Examples move online
    5 The Meta Data File
    6 See so

Why is there a problem?

The existing examples system has issues, perhaps in that it has not keep up Lazarus's own rapid development. There are a number of issues identified (in no particular order) -

    Linux Lazarus installs based on (distro) Packages have the Examples in read only space.
    Most examples do not have any indication of the topic covered other than file/project name.
    Examples don't have a category system identifying who target audience is, beginner to advanced user.
    Many examples are outdated, many don't, for example use the Lazarus Form Designer confusing new users who expect to see Object Inspector content.
    The system is limited to only those examples shipped in the main Lazarus distribution, cannot cover eg examples applicable to OPM.


What should the user experience be like?

    A user should be able to choose to see content appropriate to their experience.
    Be able to see a summary of what an example is about before opening it.
    Be able to open an example, have a play with it, make a few changes and recompile to see what happens. Maybe roll back to the original example if they make a full mess of it.
    Examples should be generally short, contain appropriate, relevant code focused on one topic each. But there will me many exceptions to that.
    If a user installs a third party package, eg via OPM, then any examples it contains should be treated in the same manner.
    Be useful to allow a user to browse through example content while working on a real project, copy and past a snipit as required.


How do we achieve this?

There appears to be three key steps, reviewing all existing examples, adding meta data and redesigning the Examples Window is clearly necessary. A reasonably easy to work with metadata standard will ensure ongoing performance. Ensuring that standard is complied with in new Examples may be more than we should ask Lazarus Developers to be responsible for.

Third party packages is a gray area, many do not have examples at all (so bei it), some will have examples that can work with a proposed new system with just the addition of a metadata file. There will be situations where a "forth party" will produce an example without the cooperation of the package author.

We also need to keep in mind that by distributing, indexing or referring to Examples, we take on some Duty of Care to ensure that no Example contains malicious code and, perhaps, is Fit for Purpose.

That is about all we all agree on at present!


methodology

There appears to be two broad models available, each with their own advantages and disadvantages. Choosing one or the other model and determining what our metadata file looks like is the next phase.

Its likely that the metadata design is substantially the same either model.

Both Example Model will require -

    An extensive review of all existing examples is required (for both models).
    Additional of a metadata file.
    A call for more examples.
    A means to scan for 'other' examples, such as ones in OPM packages.

Examples Remain in Distribution.

This is the KISS solution, it involves the least structural change but may not necessarily involve less work. As well as reviewing and adding meta data, we may wish to re-organize the location of packages. The extensive changes that must happen to the existing examples will need Lazarus Developer involvement.

More to come


Examples move online

Possibly a simpler change because much of it is implemented externally, at some stage the Examples Window will need to be changed in the Lazarus Distro but lots of building, adjusting of existing Examples, testing can happen without annoying Lazarus Developers.

Prototype code to download files, index projects and build a master metadata file already exists.

A very rough and ready example repository has been established at https://gitlab.com/dbannon/laz_examples

Note that you can browse the repository, just looking for snipits of code, you can download a particular Example directory as a zip file and use it locally. This is perhaps, for many users, easier than closing their existing project, opening up the example, seeing what they are looking for and going back to their real project and continuing working. But you need online access....

An application now e

--- End quote ---

Seems they put a size restriction on the translator :-) Nevertheless I think the sample should do. The overall quality is much like English->German: readable, with some passages slightly "rocky" to read, from my personal judgement I'd say that English->German was somewhat "rockier", very likely because correct German grammar ist generally a bit messier than English. Surprisingly the translation back to English turned out "smoother", I expected more "bumps" to arise, in fact there are less. This may be either caused by the fact that the original was English, so it translates back easier by reverting the process, or by the fact that English is generally having a more "logical" structure than German. Anyway, I consider both ways usable, and a sigificant leap forward when it comes to the overall quality of the wiki.

A problem which needs some research could be that Google seems to try to restrict the full usage of their Translator to Chrome users, I use it through Firefox, but I had to install an Add-on. Maybe (very likely) there are technical restrictions applied by Google if one tries to use their technology by embedding translations or live links which translate a page without Chrome or in general, if everyone does that, I am afraid this would overload their translation infrastructure by several magnitudes.

I would, however, very reluctantly try to copy/paste a translated page into a wiki, since there is a forseeable update problem once passages of the English page are changed.

So I guess this strategy would work best [for many pages]: a well maintained English original, the author (or volunteers) reviewing the automated translations, tolerating all insignificant glitches. On foreign language pages, instead of a translated source, a hint (not a link) for users that a "robot translation friendly" English version is actively maintained, and that they please use any translator they like to view it.

I'll have a look at DeepL now.

Btw, I looked at your metadata file ... what should be incorporated is a JSON element which links to the Wiki article, along with a size restriction put on the metadata "Description" element. If one has to say more characters about his sample than fits in a SHORTSTRING, he better does that in the wiki.

Armin

Nimral:
Had a closer look at DeepL.

Wow, the translation is, IMHO, even better than what Google translate delivers. I found no significcant error in your text sample, at least not within the first ~7000 characters, they have a maximum number of characters they do freely translate too. My impression is than DeepL does clearly enforce that serious usages require a payed subsription, but they do not list any prices for corporate uses.

I'ts not that I believe that everything needs to be free, but when it comes to commercial offerings I am always afraid that they do try to optimize their revenues by installing more and more elaborate licensing schemes, so that keeping up with their licensing schemes becomes a real pain.

This is especially true for today's online/cloud offerings, where you don't have the option to simply continuing using the old version forever if you don't like the licensing of the newer ones.

dbannon:
Wow, that is amazing !  I think you are onto something here.


--- Quote from: Nimral on February 03, 2022, 01:41:28 pm ---...
Seems they put a size restriction on the translator :-)

--- End quote ---

Hmm, should we promote shorter wiki page ?  Not unreasonable.


--- Quote ---I would, however, very reluctantly try to copy/paste a translated page into a wiki, since there is a forseeable update problem once passages of the English page are changed.

So I guess this strategy would work best [for many pages]: a well maintained English original, the author (or volunteers) reviewing the automated translations, tolerating all insignificant glitches. On foreign language pages, instead of a translated source, a hint (not a link) for users that a "robot translation friendly" English version is actively maintained, and that they please use any translator they like to view it.

--- End quote ---
Well, its the nature of Wiki's (and the way we use it, 'dynamic docs' that the content will change. Manually translating is hard, keeping a manually translated page up to date even harder.

Yep, I'm thinking, an 'automatic' google translate after every update. And a call out for native speakers to immediately review.


--- Quote ---Btw, I looked at your metadata file ... what should be incorporated is a JSON element which links to the Wiki article, along with a size restriction put on the metadata "Description" element. If one has to say more characters about his sample than fits in a SHORTSTRING, he better does that in the wiki.

--- End quote ---
Hmm, a Wiki link as an attribute ?  Yes, I like that. There are already a couple of examples I have come across that refer to wiki. Makes sense.

I agree it needs to be short, but going over SHORTSTRING occasionally is unavoidable. But, yes, short as possible is good.  A few examples do have a readme.txt and thats where detailed instructions belong. I mention the readme.txt (where it exists) in the metafile (eating into my 255 chars ;-)  )

We also need to look at ways to i18n the metadata. A translated master thats generated by having eg po/EXAMPLE.es.ex-meta in each project is probably simplest, ignore that directory when downloading.....

Davo

Navigation

[0] Message Index

[*] Previous page

Go to full version