[wiki] Textbook Terms and Terminology

saccade · 2008-12-19 22:55:17

Tackling a long wish of mine (german Textbook) I stumbled over a bunch of terms used in Textbook.
As far as I can see there are discussions and decisions about terms, but they are spread over a lot of topics and difficult to find.
So I’d suggest a “Terms Topic” (or extra part?) where discussion and decision about terms best used have their place.
And best possibly it should be clearly obvious what terms are adopted actually and currently in a summary – and discussion so far referenced from there.

Is it possible to achieve something like that?

And of course that should include the english origin as well as translations (german from my point of view).

If there would be something like a table, which puts together all languages (or related bunches of them), each translator could even profit and get ideas from lurking into what other translators/languages did.

Also misleading similarities could be avoided,
e.g.: if I translate “building blocks” in German normally I’d take the term “Baustein” – but that’s exactly the term used in german-localized-txp for “form”. So in translation of “building block” I’d better translate different (e.g. “Bauelement” or better “Komponente”) to not permix it with the too tight related form/Baustein.
I can make this a rule for me, but it’d surely improve Textbook translations if those decisions and suggestions could be easily perceived by all translators.

Destry · 2008-12-20 00:43:46

This is a great idea, saccade, and for exactly the reasons you describe.

Terminology is an important part of any documentation effort under controlled conditions, and arguably more important in open source projects because the contributions can come from anyone with any background. Even in English alone there are differences of opinion. Sometimes what is accurate is not necessarily popular. For example “tab” versus “panel” when talking about the different admin side screens. The “tab” is the little dog ear that opens the “panel,” but most people refer to the actual panel as tabs.

I think we’ll see some good debates from this. :)

I’m reluctant to use a table bcause 1) tables are not easy to juggle in the wiki, 2) it could easily become too wide for the layout if many languages are involved, and 3) maybe there won’t be a lot of words that need defined. Also, this idea of “defining” words is not exactly accurate here. What we are talking about more than definitions is semantics. Thus I propose this page, help:Documentation Semantics, which I’ve added a link for under the Translation help contents.

On the page itself we can start with definition lists, where the English term decided on is the dt and all the translation terms (each language) are the dd’s underneath. So in the wiki it’s simply this:

; English term
: French translation
: German translation
: Hungarian translation
: etc

No definitions, just terms. As (or if) the page grows, we can decide later how to further organize it, but something linear like this will be better in the beginning, I think.

Destry · 2008-12-20 01:50:57

Following up on the expression “building blocks,” I used that expression to describe the different key Txp components in the two such indicated articles at my site. They get a lot of hits and the expression, I guess, has started to spread around. I used the expression because I was writing for Txp newbies, but I can see where it would be hard to translate evenly across languages. In English it works because the expression is meant to be plural, referring to all the different ones at the same time: sections, pages, styles, etc. The minute it goes singular, then you simply refer to the component itself, whether a section, a form, or whatever.

saccade · 2008-12-21 00:25:46

Hi Destry,
thank you for the quick response.
I’ll try to begin the first definition lists.
One thing I think is necessary: A first entry which shortly lists, which terms are to be replaced (or deprecated) by the acknowledged term in Textbook. It could also be shown by strikethrough, if a strong visual indication is wanted.

For instance:
admin-side (texbook-term for “backend”, “back-office” and similar) (de) Redaktionsseite, (fr)

How should we indicate the language in the list? I proposed (de) and alike for now, but maybe there is a better solution.

saccade · 2008-12-21 01:20:29

As for the expression “building block”: the expression is fitting quite well and working perfectly in english, where it doesn’t appear in txp menues itself and so couldn’t be mixed up with any menu or function. (to be more exact: It doesn’t collide with “form”, see below).
But it is a good example of problems in its translation into another language:
My example only regards the adequate german translation of “building block” which is “Baustein”, which but exactly matches the german term used for “form” in the german textpattern language file. So a mere translation would easily provoke misunderstandings.

To be honest: “Bausteine” never quite satisfied me as a translation for “forms” – though I have hugest admiration for what the translators did and how well the german language file is made. A big, big thank you for that!
The german term “Bausteine” isn’t quite coherent with its context terms (“vorlagen”), it is too little specific and I for myself needed some time to realize its meaning.

But now that “Bausteine” is used for “forms” it cannot sensibly be used for “building block” as well – it will cause misunderstandings at least for newbies.

Brainstorming for solutions also let (past tense!) me think of possibly changing “Bausteine” in the german txp files in favour of another, better term. That would free the general term “Baustein” for “building block” and describing the overall txp architecture in a clear and linguistically fine way.
But on one hand I have no alternative at hand (and didn’t think long about it) – on the other hand I don’t think it would be a good idea to change an term that has been spread already so far. (Or would someone correct me?)

At the moment I’d think proposal2 as the best (=template modules).
And proposal1 would keep “Bausteine” but make it quite clear, what they are for and would make it easy to distinguish it from other uses of the word “Bausteine”, for instance “Bausteine von Textpattern” for “building blocks of textpattern”.

To be clear: I don’t really want to change something very good. Just thinking over possibilities and refinements – if they are.

Destry · 2008-12-21 14:09:37

saccade wrote:

One thing I think is necessary: A first entry which shortly lists, which terms are to be replaced (or deprecated) by the acknowledged term in Textbook. It could also be shown by strikethrough, if a strong visual indication is wanted.

Yes, good idea. This will be helpful.

How should we indicate the language in the list? I proposed (de) and alike for now, but maybe there is a better solution.

Yes again, that’s probably the safest course.

saccade · 2008-12-21 14:58:37

Hi Destry,

great, I started some beginning lists.

Now what’s the preferred TextBook term regarding “tab” and “panel”?

Destry · 2008-12-21 15:47:25

Oh, that’s a tough one, because of what I was saying before about what is accurate versus what is popular.

These sentences makes perfect sense to me, even if they are a bit exaggerated…

Click the Write tab to open the Write panel where the article editor is located.

- or -

You can turn comments on locally for an article in the Write panel via the Write tab.

However, casual dialog will often be like this…

You can change an article’s title by editing the article’s URL title in the Write tab.

In this case, people know what it means, but it’s technically not accurate; you don’t edit in the tab, you click the tab and edit in the resulting panel (or screen, or view…).

Open source documentation probably needs a documentation style manual started (like the industry leading Microsoft Manual of Style, for example) so more open-source-minded types might pay closer attention to the conventions, though it shouldn’t make any difference because an application is an application whether open source or not and is still impacted by the same problems with usability, semantics, linguistics, and so forth.

The question is: how accurate do we need to be before it makes the communities feathers ruffle?

Last edited by Destry (2008-12-21 15:48:43)

saccade · 2008-12-21 16:46:44

Accuracy and popularity aren’t the only coordinates to be kept in mind, but (for me) much more: simplicity (or consistency or constancy).
And in order to keep that, it’s better to stick to a clear terminology which is well thought and constantly followed. Not popularity nor accuracy will help me or any newbie anything, if one has to build his own dictionary (and thesaurus) in mind, coping with too many different words meaning the same thing.

For me it makes perfect sense always to speak of a “panel”, when it comes to anything on that panel, for instance of the “Write-Panel” (and not to mention every step, like “click on the Write-Tab on the left side…”). To speak like this (speak in concepts) will lead to the correct imagination arising in the users mind when reading.

And only once – at the beginning of manual – to speak of using the “tabs” for opening a panel and saying what exactly is to be done. (And by the way: There also could be told what to do, if you cannot use a mouse or click anywhere.)
This one really accurate reference obviously should be placed in a prominent place, surely at the beginning of documentation. (Maybe even we could add a linked page, describing “panel” in general and its tab – it could be a linked question mark after the word “panel”.)

And what could help vastly is: Every time a panel is mentioned first in an article simply show that panel – only the top part of it. Then – without any word – a user will know, that he ought to click on that ~~panel~~ tab of course.

For achieving this it should be simple to add a page in TextBook with screenshots of all tabs/panels in a finely sized dimension to be used by anyone. Readily prepared links and captions then simply could be copied by contributors.
I’m willing to do this.

So I’d summarize this thoughts as follows:

Let’s have

a few basic very accurate pages for the concepts of operation (e.g. using a panel by clicking on its tab),
throughout the rest a clear bunch of simple and consistent concepts (e.g. “panel” as operating place).
whether the wording of these concepts follow accuracy or popularity can be decided one by one (I stick to accuracy of course, but sometimes popularity could be simply better)
support the use of these concepts by providing resources simply to use (e.g. screenshots and links).

Last edited by saccade (2008-12-21 17:12:02)

saccade · 2008-12-22 13:56:05

I now added two new Help-pages:

Screenshots Menu english

and

Screenshots Menü deutsch

on which there are collections of ~~screenshots~~ figures and basic captions to be copied from.

As a first load I uploaded full bars in english and german.

Yet to do (in the queue):

Small images (all the same size) with just the relevant parts.
marked images (with arrows, nice ones)
full panel images (already shot, I first have to wipe out personal info from them)

A Question regarding the captions:
Maybe it would be helpful or better to also mention the first level panels (e.g. “Content > Write”?

And, sorry, the full bars exceed the provided place, but I didn’t manage to have them placed smaller. There also is a problem of how to present them: If someone should be able to copy easily, then a thumbnail wont work, because he will copy it as thumbnail as well.
Here, I think some sort of css-shrinking perhaps would suit better.
Anyway, in most cases these wouldn’t really be used within TextBook pages very often. The smaller ones surely work better. But the full bars are a good resource if someone wants to make his/her own smaller part (different from provided ones).

Last edited by saccade (2008-12-22 14:30:37)

saccade · 2008-12-22 14:29:43

Oh, just remembered the “NO SCREENSHOTs” in the help. ;-)
Sorry about that, I shouldn’t have called the images “screenshots”, but rather “figures” – what they really are.
And I forgot the “Help:” in the german page.
Just don’t want to leave dead pages (by creating new correct ones). Is there any way to simply rename a page in TextBook?

Destry · 2008-12-22 23:30:49

Saccade,

The way the current Admin-side pages are currently setup is to have a sized (cropped) piece of the admin-side tab menus in place at the top of the page for a given panel being described. So for example if you go to the Write panel you see the relevant tabs to click to access the panel. Although not finished yet (unless speedy Bloke has in fact finished it), this will be consistently done for every admin-side panel page in the wiki documentation.

In my opinion, the only thing we need to do at this point, which gets back to your original motive, is to develop (as needed) the terminology list to use for the gray areas so it’s available for contributor reference. Then people simply start editing terms where they exist if they are not already what will be officially defined for use. So, for example, if we are going to go with “panel” (what is accurate) instead of “tab” (what is popular) when talking about a given admin-side screen, then we would change things like the mini-nav headers in the admin-side pages (e.g., Content sub-tabs to Content sub-panels), and things like ‘The write tab (or panel)’ to just The Write panel (capitalizing “Write” because it’s the actual name of the panel), and so forth.

I’m not sure there’s a need for the extra screenshot pages, instructions and whatnot, it’s just too much to maintain and for people to take in. I would say keep it as simple as possible and in context of the documentation that exists. In other words, just edit the text where it needs it against the terminology list.

(As for changing the names of pages, if pages are really needed, it’s better to just recreate it with the new title you want and delete the former. This avoids a lot of unnecessary redirects and dead pollution in the All Pages location, which is used by wiki admins and editors to keep the structure orderly. When we know for sure we need the page, I can do the deletion.)

Last edited by Destry (2008-12-22 23:36:12)

Textpattern CMS

Textpattern CMS support forum

#1 2008-12-19 22:55:17

[wiki] Textbook Terms and Terminology

#2 2008-12-20 00:43:46

Re: [wiki] Textbook Terms and Terminology

#3 2008-12-20 01:50:57

Re: [wiki] Textbook Terms and Terminology

#4 2008-12-21 00:25:46

Re: [wiki] Textbook Terms and Terminology

#5 2008-12-21 01:20:29

Re: [wiki] Textbook Terms and Terminology

#6 2008-12-21 14:09:37

Re: [wiki] Textbook Terms and Terminology

#7 2008-12-21 14:58:37

Re: [wiki] Textbook Terms and Terminology

#8 2008-12-21 15:47:25

Re: [wiki] Textbook Terms and Terminology

#9 2008-12-21 16:46:44

Re: [wiki] Textbook Terms and Terminology

#10 2008-12-22 13:56:05

Re: [wiki] Textbook Terms and Terminology

#11 2008-12-22 14:29:43

Re: [wiki] Textbook Terms and Terminology

#12 2008-12-22 23:30:49

Re: [wiki] Textbook Terms and Terminology

Board footer