[Smaug] Smaug Web pages

David A. Gatwood dgatwood@gatwood.net
Thu Jan 31 11:27:02 2002


On Thu, 31 Jan 2002, Rick Moen wrote:

> Since you're doing the lion's share of the work, I defer to you on this 
> point, but please consider:  In my experience, the information people 
> look for most on a user group site is "where, date, time" event info.
> Putting summary details of this as prominently as possible (with the
> most-crucial data in "strong" or "em" tags) on the main site page has
> two benefits (BIG HONKING benefits, methinks):

Still looking for a good way to do it that doesn't diminish the page's
overall look.  I think I have an idea, but I can't work on it right this
second.


> o  It's what viewers seek most often.
> o  Such text calls your attention to it, when it needs updating.

That last one is a very good point, which would make the news section even
better, since it's on the top of -every- page.  ;-)


> The link from the main page is to "meeting.html".  But there is no
> such page:  The file you created for that purpose was "meeting.sub".
> So, you've banished event details to a broken link.  Oops.

Fixed.


> If and when you have time, it'd be really, really helpful if you could 
> take half an hour and write a short piece outlining the logic behind
> (and primary techniques used in) the site, naming conventions, etc.  It
> should end up eventually, I think, in the project pages' Doc Manager, in
> part because that's where aspiring site maintainers are going to look
> for our collective knowledge to be documented.

Sure.  No prob.


> I know coders hate writing documentation:  That's why I'm volunteering
> to do as much of the annoying parts as can be taken off your hands.  But
> half an hour of your time now will probably go a long ways towards
> avoiding having well-intentioned but poorly informed shlubs like me
> messing up your work.

I write documentation for a living now.

http://developer.apple.com/techpubs/macosx/Darwin/General/KernelProgramming/


> (I also know that coders are incurable optimists.  That's why it's handy
> to have a sysadmin like me around to sprinkle pessimism and caution on
> the assumption that everyone's going to think and understand before
> leaping in and fscking everything up.  ;->  )

Heheh.


> Anything we can do to make the HTML _self_-documenting is probably going
> to be good, too.  What's clear to the original creator isn't necessarily
> at all obvious to others trying to help.

Working on it.


> When I tidied up your original HTML, one of the things I did was put
> whitespace and line-breaks in the table tags so they were readable.  The
> tables were the one single, murkiest, most difficult to read part of
> your design.
> 
> Your revision wiped out my cleanup of your table formatting.  (Of
> course, I _should_ have done it in the template, as well.)

The extra whitespace also changed the way the table displayed on several
browsers.  I agree that the code looks hideous and hard to maintain,
and cleaning it up is on my weekend list.  It's very difficult to make
the changes in a way that doesn't break anything, though, so it's not
something I want to rush through right this second.  :-)


> I also had yanked "base URL" tags out wherever I encountered them.  Why?
> 
> o  Because they seemed to have zero utility, in the first place.
> o  Because they made the site contents non-portable.

And they break Netscape.  That was what was causing netscape to not show
the graphics.  :-|  Those should be gone now.  If they aren't, then I
goofed up.  They only reappeared briefly last night because they hadn't
been removed in the template.  :-)


> While I was at it, I fixed all absolute URLs, making them relative, 
> and eliminated the common error of linking to "index.html" instead of
> to "./" (and to "index.html#foo" instead of "./#foo").  Why?  Think
> about caching for a moment, and you'll see why.

Reintroducing those was inintentional.  I'm not convinced I write "./" as
a link, though.  I suspect somebody else created those links originally
and I just copied and pasted them into the new design without thinking....


> Your site revs have reintroduced hyperlinks like "/index.html" again.
> In my view, that's breakage from both the absolute-path standpoint 
> and the caching one -- and should be fixed.

Actually, the /index.html might have been necessary at one time during
initial design -- I might have originally had some things in
subdirectories and wanted to include the same HTML code.  I really don't
remember on that one.  It certainly isn't needed now, though, and I'll be
happy to fix that in the template and migrate the changes out when I get a
minute.


Later,
David

---------------------------------------------------------------------
                    Check out my weekly web comic:
                     http://www.techmagazine.org