Re: Really Quick Guide to Good HTML

> 
> I've written a basic guide to html, meant for the users 
> here at NPS (or anyone else who cares to browse) and it 
> occured to me that a learned opinion might be helpful.  
> I would appreciate it if you would browse by:
> 
> http://www.nps.navy.mil/internal/tutorial/q_htmlguide.html

A couple of initial comments:

1) Excellent idea. HTML in 10 minutes. Makes those books in the store 
"HTML in a week" seem a little, well, padded?

2) "HTML ... is really just ASCII text with extra codes
    thrown to better identify the content of the document."
    
Yes, but please avoid saying ASCII. There is no need for it, and it 
is misleading. I appreciate that your primary audience is American, but 
then a not inconsiderable percentage of Americans speak Spanish and no 
doubt appreciate being able to put those cedillas into their text.

In the context of your ten-minute guide I suggest replacing "ASCII text" 
with "plain text".

2) "However, HTML is not a WYSIWYG (what-you-see-is-what-you-get)
   format.  Each web browser may display your document slightly
   differently, and most let the reader customize how documents are
   displayed."

Rather than put that as the end, where it sounds like admitting a problem, 
try putting it at the start of the introduction and make it into a benefit.
Try this:

   HTML is not a WYSIWYG (what-you-see-is-what-you-get) format.  It does
   not specify what font will be used or how a page is layed out.
   Instead it just identifies sections of text as headings, lists, and
   so on.  This makes HTML very easy to write.  HTML is just plain text
   with extra codes to identify the content of the document.

   Remember, though, that each web browser will display your document
   slightly differently, and most let the reader customize how documents
   are displayed.

3) You confuse tags and elements. It is probably useful to explain what 
they are. HTML is made up of elements. An element can consist of either a
single tag, like this:

<hr>

or a paired start tag and end tag with some stuff in the middle.

<h1>An important heading</h1>

The stuff in the middle can itself contain nested elements.

Then go on to explain about the angle brackets. this is easier to do *after* 
the reader has seen a couple of examples, wheras you do it before they have 
seen them- so they have to try and imaginge what this will look like.

Introducing the idea of "nesting elements", rather than "codes inserted into 
the document",  gives people a better idea, I think, of why they cannot 
do this:

<a href="foo><h1>stuff</a></h1>

4) "Every document should have a title."

Since your guide is about writing good HTML, rather than stuff that will 
probably work, I suggest altering this to

  Every document must have a title.

which is what the HTML2.0 spec says. You can back this up in one sentence 
by saying that indexing engines use this information, so leaving it out 
could mean people don't find your documents.

An ounce of self-interest is worth a pound of "do this to conform to 
the standard" ;-)

The other points you make about titles are good.

5) standard wrapper:

html can be missed out in all html 2.0 documents.  Your first sentence is
not strictly true, and "this can vary" just introduces uncertainty.

I suggest you just say that the entire html document is a single element 
and the start and end tags are <html> </html>, and leave it at that. Save
your energy for getting them to insert <head> and </head> which is much 
more important - and will become increasingly important with later revisions of HTML.

I suggest that you introduce these by saying that the head element contains
information about the document, which is not displayed as part of the 
document, wheras the body contains the document itself.

6) </p> can always be omitted. Again, if you introduce elements early this 
becomes easy.

   To put text into paragraphs, use paragraph elements:

   <p>This is a pagagraph</p>

   In practice the closing </p> can always be omitted.

The main thing is to ensure they understand paragraphs are elements, rather 
than believing that paragraph tags introduce line breaks (which your text 
does sort of imply) and to avoid the idea that <p> separates paragraphs, 
rather than starting them.

I find it handy to have an example:

<h1>Big Heading</h1><p>A paragraph</p>

This shows them several things

- yes you put a p right after the end of the previous element, to *start* 
  a paragraph
- the line breaks and spacing in the HTL source are irrelevant

I found your text on "extra lines" gave the wrong impression here.
Rather than concentrate on the visual effect, I suggest you concentrate
on the semantics.  Use an address or something to illustrate br, and say
this is all one paragraph.

7) Headings

Good, but say "H2-H6 are the other headings,
each being consecutively less important than the first."

8) URL

this is used way before being defined. People who are going to write 
HTML are probablt used to URLs from browsing, heck even from adverts. 
I suggest you put the descripotion of URLs into a "sidebar" - another 
document. This stops it interrupting the flow of text and means people 
can read that descriptionor not, as they need to.

"Be aware that anchors can be placed within paragraphs ..."
This section will also benefit from introducing elements early on.


In general your 10 minute guide is great and just what is needed. I would 
certainly recommend it over the NCSA beginners guide, which is well past 
it's sell-by date. I hope you find my comments and suggestions helpful.



-- 
Chris Lilley, Technical Author and JISC representative to W3C 
+-------------------------------------------------------------------+
|  Manchester and North Training & Education Centre   ( MAN T&EC )  |
+-------------------------------------------------------------------+
| Computer Graphics Unit,             Email: Chris.Lilley@mcc.ac.uk |
| Manchester Computing Centre,        Voice: +44 161 275 6045       |
| Oxford Road, Manchester, UK.          Fax: +44 161 275 6040       |
| M13 9PL                            BioMOO: ChrisL                 |
| Timezone: UTC        URI: http://info.mcc.ac.uk/CGU/staff/lilley/ | 
+-------------------------------------------------------------------+

Received on Tuesday, 20 February 1996 20:15:30 UTC