RE: Language techniques: biggish changes

I really like the new introductory material, in particular (2)Why
specify language? -- I think that is an excellent addition.

Although it is a departure from previous practice, I think that making
the document "more self-contained" ie. including information found
elsewhere in FAQs, etc. is goodness for the reader. I think I have
expressed previously my concern that our division of material into FAQs,
techniques, tutorials may be somewhat less than 100% intuitive to 100%
of our audience, so the practice of repeating some information in
different formats helps ensure that as many readers as possible find the
information they need where they first look for it.  

Re: the TOC, again I very much like the new, simplified version based on
Deborah's suggestion. I think Richard did an exceptional job in making
them short yet highly informational.  And again, although a departure
from previous practice, I think it is a good one, being more "inviting"
to the reader, ie. less visually intimidating.  I do, however, take
Richard's point. Would we want to experiment with the possibility of a
"click here for an expanded version"?

Nits to follow (as always).

best,
susan

-----Original Message-----
From: Richard Ishida [mailto:ishida@w3.org] 
Sent: Tuesday, February 08, 2005 3:04 AM
To: GEO
Cc: wendy@w3.org
Subject: Language techniques: biggish changes
Importance: High




After reading Deborah's recent comments on the Language techniques
document, I have created a proposal for new material and organization.
Please take a look at this and voice your opinions by email and/or
during the telecon this week.

If I do not hear voices to the contrary, I will begin to make permanent
changes to the document towards the end of this week, ie. after the
telecon.  I also plan to remove the current change marks at the same
time - so please comment on those if you are intending to.




[1] Additional introductory material
====================================
I have quickly written up three new sections:

2 Why specify language?
3 Important concepts
    3.1 Primary language
    3.2 Text processing language
    3.3 Relationships with character encoding and directionality 4
Mechanisms for declaring language in HTML

You can see these at http://www.w3.org/International/geo/html-tech/test
(Note that I temporarily left in the following 'Definitions' section
(section 5) so as not to break id-refs.  Assume that that will not be
there in a final version.)

The effect of adding these is to make this document more self-contained
for someone wanting to know about language declarations. Previously we
had aimed to largely document just the techniques themselves, and use
pointers to faqs, etc. to flesh out the areas in the new sections.  

These additions make the document much more the type of document you
might read end to end - rather than just dip into for clarification on a
particular technique.

Note also that it duplicates some of the material in Faqs and tutorials.

Is this a good approach?



[2] Changes to the table of contents
=====================================
I have had people comment on how useful the toc was because it included
the text of the techniques.  Indeed I have found that very useful myself
for getting an overview of the document.

It is arguable, however, that such information is available in the
outline document.

As an experiment, I implemented Deborah's idea of shorter titles for the
techniques in the toc.

See http://www.w3.org/International/geo/html-tech/test#contents for the
new approach.

See
http://www.w3.org/International/geo/html-tech/tech-lang.html#contents
for the current approach.

Should we adopt the new approach, or return to the previous?




[3] Reordering of techniques
============================
I made plans to substantially reorder the techniques.  The proposal is
NOT yet implemented in the document linked to above.  You should instead
look at the language section of 
http://www.w3.org/International/geo/html-tech/outline/html-authoring-out
line.html

(Note that the section "Identifying in-document language changes"
duplicates material, and would NOT appear in the techniques doc - only
in the outline.)

The rearrangement helps to more clearly separate primary vs text
processing declarations, and improves the clarity of the section
headings.

I have not followed Deborah's suggestions exactly, but I think this is a
good alternative.

Do you have any objection to this new order?




Comments asap please.
RI



============
Richard Ishida
W3C

contact info:
http://www.w3.org/People/Ishida/ 

W3C Internationalization:
http://www.w3.org/International/ 

Publication blog:
http://people.w3.org/rishida/blog/

Received on Tuesday, 8 February 2005 17:10:29 UTC