w3c / i18n-drafts

A place to edit articles, tutorials, and the like for the /International subtree of the W3C site. Also, captures issues and comments.
64 stars 62 forks source link

[questions/qa-http-and-lang] Understanding the scope of the article #177

Open iatomic opened 6 years ago

iatomic commented 6 years ago

[source] (https://www.w3.org/International/questions/qa-http-and-lang) [en]

terrible article...total chaos....and no examples HOW to USE the language ...lots on how NOT to use

r12a commented 6 years ago

What information, specifically, were you looking for?

asmusf commented 6 years ago

I must say that I feel a bit of a disconnect as well, when reading that page. It seems to approach the issue from a very narrow technical point and then gives an answer that's a bit more general.

I was expecting something like this:

A lang attribute on elements sets the language for that piece of text. Not needed if it's inherited (true?) from an enclosing element, ultimately the html tag.

There's no way to set information defininig a page as multilingual (true?)

if no tag on html, browsers may use http lang info, which may also be used in language negotiation (getting the correct document to the intended audience).

Old meta data construct now obsolete - don't use. (editorializing on the side effect / shortcomings of this may or may not have a place in this article - generally not helpful for people trying to figure out what to do).

[If the above outline is misstating something, chalk it up to the way the existing article(s) can't be skimmed quickly.]

iatomic commented 6 years ago

I agree....how about some examples on HOW to use a tag. Waxing poetic and thooretical on something that PRIMITIVE is absolute hot air. this is not theoretical quantum physics but practical science - i want to skim an article and know right away what is to be used and how.

r12a commented 6 years ago

This article is indeed intended to address a narrow technical point, ie. "For HTML, should we put language declarations in HTTP headers and meta elements, and how are they different from those in language attributes?" (The background information about metadata vs text-processing is needed in order to understand those arguments, and we regularly have to refer spec developers to that also.)

Wrt skimming, the QUICK ANSWER panel summarises the recommendations for this article. Do i need to make that clearer somehow? It's already highlighted.

If you want general information about how to use the lang attribute, follow the link in the intro where it says

For more information on the use of language attributes see Declaring language in HTML.

Or look at the additional reading links at the bottom of the page.

Perhaps i need to say the above more clearly somehow in the intro? Would it help if there was a paragraph just above the bold text at the start of the QUESTION section that said: "This article is specifically about the question in bold text below. If you have a different question, see XYZ or the FURTHER READING section at the bottom of the page. The quick answer section summarises the advice on the page."

Or should that go at the start of the QUICK ANSWER section, since i get the feeling you skipped over the intro??

asmusf commented 6 years ago

Looks like people end up there when not looking for that small technical point. Is it needed? Is the answer perhaps too detailed, therefore making the article pop up in searches for general info?

r12a commented 6 years ago

It is needed, yes, but not as often as the general info about using lang attributes. I've been considering various ways of telling people more clearly what a given article is about, and what the alternatives are.

We could do things like the following:

  1. when an article is focused on a specific question, tell the reader explicitly that that's what the article is doing, and point out in words what the question is (rather than assume that the bold is sufficient). (I considered putting the whole question as the article title, but i think it would be too long in many cases.) We do have some of that in the intro for this article but maybe people skip that and go straight to the ANSWER section?
  2. provide links at the top of the article to alternative questions and wider ranging articles. We could perhaps move the links to the techniques index from the FURTHER READING section up to the top of the doc. It sounds like we also need to explain what those links are, rather than just have the links.
  3. remove the shading and special styling for the QUICK ANSWER section, and just call it ANSWER (because some people seem to skip past it?!). Then add a standard paragraph at the end explaining that the rest of the article contains additional detail for those who want it. Perhaps add more links to the detail throughout the brief answer, at relevant points.
  4. maybe remove the 'intended audience' information near the top - i'm guessing that few people read it. Or perhaps if we put the extra signposting stuff there, so that it was longer and had some colourful links, that would make it more obvious??

Basically provide more text and links to establish whether the reader is in the right place, and tell them what to read. I was rather hoping that people would figure that out pretty easily, given the styling, but maybe not. When we started writing these articles, we felt there was too much text at the top, and subsequently paired things down as much as possible, trying to get people quickly to an answer, but perhaps we went too far.

asmusf commented 6 years ago

The problem, as I see it when re-reading the article is that while the question ostensibly is only about the HTTP content language, the answer really drags in everything. (And because of that, search will correctly conclude that the article gives a more general answer and lead people there).

I think this needs to be refactored.

First, split off an article solely about HTTP-equiv being obsolete. In that article do not explain any alternatives, just give links.

Second, trim the HTTP content language FAQ to: What language info should be set in HTTP headers? You will find your quick answer reduced to one (instead of three) items (which is a good sign that the article really answers one question).

Mention that language info in the document normally overrides HTTP headers, but remove all description of what that language info is (replace by link). (Add link to the article on obsolete HTTP-equiv, but don't elaborate other than stating that this is obsolete).

Make sure any of your links give the same levels of answer as the discussion currently embedded in this article (not just covering the same ground but equally focused). Perhaps consider a FAQ like article on "What to put into a html lang attribute" in parallel to the existing tutorials (for quick refresher and so people don't have to wade through too much to get a quick answer).

If done right, search won't lead people any longer to the focused HTTP Content-language article if they are just trying to get info on setting language tags. (Of course add links to that reduced article from the new articles).