Mail Starting 5/30/98
13 messages, ending 6/17/98
Last modified: 6/18/98
This section is in chronological order, since it is being released as one piece.
Send your comments to:
From: Arnold G. Reinhold
Date: 5/30/98
Subject: re: www.gooddocuments.com
[this is a forwarded reply to a letter from a friend of his who works at Trellix, used with permission]
Well, I think it is a very interesting and important idea. It is alos
ambitious. There is an enormous amout to be said on this topic and a lot of
differing opinions. Writing well isn't easy, takes more work than one
expects and not everyone can do it. But tips like those on your site can be
very useful.
The site itself has some nice stuff, but it needs a lot of work and
additional material.
First you should hire an editor and proofreaders.
A good editior can make a big difference. One sentence now reads "By using
clickable image maps, such that when readers click on the representation of
a particular page in the document they are immediately taken there, allow
them to navigate directly."
Proofreading the final version is also important if you want to make a good
impression. One subhead now reads: "The author knows best how write them."
My publisher allows each proofreader to proof a given book only once.
You also need to follow your own advice. There are very few lists on the
site. The paragraph after "Overviews should be concise" is too wordy.
Some problems may be the Trellix to HTML related. For example, on my
browser, all the subheads are in plain text (not bold or larger font).
AS for additional materila I would like to see sections, written by pros,
on the following topics:
Typography
Graphic design
Use of whitespace
More on understanding your audience (you list two kinds of readers.
There are more.)
Use of humor
(The paragraph "This paragraph is even worse. It is one of the worst
paragraphs in this entire
document, ..." is actually one of the best on the site. The humor in
Dummies books is really corny, but it makes boring material readable and
has killed a lot of trees.)
Developing a site syle sheet
Multi language issues
Dealing with time dependent materials.
(Does Trellix have tools for this? They would make a valuable feature.)
General English style
Writing for people with disabilities
Importing large quantitiles of existing material
Record retention issues
Below is some related stuff I wrote in The Internet for Dummies Quick
Reference (It is copyright by IDG Books) [not reprinted here, since we have
not gotten permission from IDG, excerpted from "The Internet for Dummies
Quick Reference", 4th ed., Part IX]
On the whole, I think "gooddocuments" is a very worthwhile project and one
that makes sense for Trellix, but realize you are biting off a lot.
Arnold
EMail to Arnold:
I agree with you about editing. In the past, I never sent out any documentation I wrote without giving it to an editor first. This was even in the days of Software Garden, when I was on a shoestring budget and the money came right out of my pocket. I know how much editing helps. Unfortunately, the Good Documents web site is of low priority here at Trellix until it gets a bigger following (which it is getting). At that point, we'll spend more resources. Also, at this early point, the roughness of my writing is part of the style. While it gets in the way for some, it appeals to others, plus it is more typical of the writing you will find on an Intranet.
Reply:
I understand the constraints of a startup -- too many things to do with
limited resources -- but this site really needs to read will if it is to
sell itself. Maybe something less than a full blown edit job might work.
Regards,
Arnold Reinhold
The new section I added (the one on frames) went through more extensive editing (by someone other than myself) than the older ones. I will do even more in the future, including fixing some of the problems you point out. -DanB
From: Vadim
Date: 5/30/98
Subject: Maps
Hi Dan,
Like the site. Here is few things you may find relevant.
I would like to see navigational maps displayed in the separate floating
window. Like Microsoft.com
displays help tips on their site. Also would be nice to see a history of my
travel in the document next to the map. Having history in the browser is not
good enough because browser does not know the boundaries of the document.
================================
Now a bit of a philosophical discussion. I like to read non-fiction books.
The problem is that skimming is almost impossible. Usually author dedicates
the book to the set of ideas he is trying to prove.
There always assumptions and conclusions, examples and similarities to other
fields.
Some times reader spends 90% of the time to read proofs they already agree
with or examining
obvious examples as author is trying to steer reader to main point. Same is
applicable
to business writing.
I would like to see a way to walk the document fast
concentrating on details witch I ( as a reader) consider important.
It can almost be done as an interactive process where document asks
questions and
displays next section of the document depending on the answers.
Something like this:
Do you agree with this assumption?
(yes) Go to the next point.
(no ) Let me tell you more about this.
Vadim
Neat idea! -DanB
From: kolson
Date: 6/2/98
Subject: Setting a Bad Example
>
> www.gooddocuments.com
> How to write for the INTRAnet
> A web-site that discusses how to create good business documents in the
> linked, on-screen environment of Intranets and the Internet.
> Last modified: Monday, June 1, 1998
> News
> Additions and changes to this site; items of interest to our readers
> About this site
> How to write everyday documents for the Web, started by Dan Bricklin
> of Trellix Corporation
> Where to apply these ideas
> When you have to write something that someone else will need to read;
> not for designing a cool web site
> Philosophical discussions
> Ideas behind the techniques covered here, and how they came about
> Techniques (A "How To" section)
> Do's and don'ts, with examples
> Samples (A "How To" section)
> Cookbooks and samples for specific types of documents
> Mail
> ...from others
> Related sites
> Many good writers are also grappling with these problems. Read what
> they have to say.
> _________________________________________________________________
>
> (c) Copyright 1998 Trellix Corporation
> All Rights Reserved.
> This web site was created using Trellix 1.0 from Trellix Corporation.
> For more information on Trellix 1.0, see the Trellix web site.
> Comments to: comments@gooddocuments.com; Webmaster:
> webmaster@gooddocuments.com
Here's how it looks in Lynx.
I can't believe a page cited as how to do it right would start out with
frames and no Lynx-friendly page at the outset. This is one of the most
egregious errors companies make in letting designers give them a bad
reputation. It's the web equivalent of the folk who sent out demo software
requiring high-end displays to sell display upgrades.
I'll be back when the graphic, frame-enabled browser is fired up to see
what your site has to say, but I can't say I have a good first impression.
--Kirt
I'm sorry if you couldn't read it with Lynx, but the site was designed for the people implementing content for an office intranet, not the general internet, and we had to set the baseline somewhere. I don't believe it's like "requiring high-end displays to sell display upgrades" since it is the writing I want to upgrade, not the browser -- I assume office people already have Netscape 2.0 or IE 3.0 and above. The log files seem to show that less than 2% (maybe less than 1%) of the people who visit (even for one hit) this site are not in that category. Unfortunately, you were one of them...
-DanB
From: James Armstrong
Date: 6/4/98
Subject: Impressions on Good Documents
I found the content of Good Documents to be interesting and useful.
Extremely good advice especially where more and more documents are
showing up in HTML. With the use of the new Trelligram utility being
Beta released by Trellix along with HTML functions being added to word
processors, I can see that business communication may also take a
more"Web" related direction.
One comment to add:
I have a real problem with a 'next page' link showing up when there is
no next page. Your links to a next page should either disappear or
change color when not linked.
Other than that, I like the site. It's a good, clean looking,
non-cluttered site. What a relief !
Jim Armstrong
The "next page" link problem is an artifact of using Trellix 1.0 to do the Next/Previous automatically. It will be fixed in the next, upcoming Trellix release, which I will use when I redesign the site. Sometimes I hand-link the Next/Previous so you won't have the problem. At least text links (like on this page) don't look linked (no underline). -DanB
From: Sandra Wulff
Date: 6/4/98
Subject: Printing info from your website
Hi,
I am very interested in the information provided on your website but I am
unable to print it out. Is this by design? or am I doing something wrong?
Look forward to your response. Thank you.
Sandra Wulff
Probably a problem with printing framed pages with your browser. Microsoft Internet Explorer 4 prints with frames. Netscape Navigator may require you to click within the frame you want to print and then do the print. (This is one of the problems with frames, sigh... others are listed in the Frames technique) -DanB
From: Marilyn Brown
Date: 6/7/98
Subject: Writing for Elderly
The future elders will never be lonely due to computer
tecknology.Today much more knowledge needs to be available to them
and in more simplified ways. This would enable the elderly to move
about on the internet without becoming involved with much clutter that
crepts in distracting from what is best on the net. Easy to follow
instructions are needed for elderly to enjoy the internet to enable them
to be fearless when using the internet. Much more could be
written on the subject to help the elderly take part in the modern day
computer world. Thank you.
From: Mary Utt
Date: 6/8/98
Subject: Gender neutrality
>Aid the busy reader by telling them what they will find if they read
further.
No need to change this line. This is actually "old established good
usage"
since about the 14th century.
See
http://www.pemberley.com/janeinfo/austheir.html
Mary Utt
Thanks for the link! It's nice to know my English hasn't deteriorated THAT much... -DanB
From: Esti Lederer
Date: 6/9/98
Subject: site name
Hi,
Very nice site!!
one suggestion - as a technical writer, when I saw the site name I
thought of a more generic tech writing site (not that I am not
interested in writing for the INTRAnet).
Maybe its too late but I would change the name to: "Good Intra docs"..
Esti
From: Scott Sumner-Moore
Date: 6/9/98
Subject: Reading backwards
I read an article several months ago that explored the fact that a significant
portion of the population reads backwards.
What this means is that many people picking up a book or looking at a magazine
article will turn to the end and skim from the back to the front. I don't
recall the details of the article (or even where I read it -- it might have
been Smithsonian), but I soon discovered that I am a backwards reader.
This is one area in which paper seems to have an advantage over electronic
media.
Have you heard of this? What are the implications to writing for the
intra/inter-net? How can you provide a natural electronic experience for those
who tend to read backwards?
Thanks,
--Scott Sumner-Moore
This relates well to the type of writing we talk about here. People want to know the conclusion first, and then maybe will want to know how you got there. Reading backwards is a way of getting that from an article that builds to a conclusion. -DanB
From: Mark Roberson
Date: 6/10/98
Subject: Web Reading and columns
This site is somewhat easier to read than most. There is still a problem
that you have not addressed. You site newspapers as a good resource but
you never mention columns. I like reading books for technical reading. I
have always been a speed reader. Roughly about 2000 wpm. When I read
stuff off of a screen it slows down to about 1000 wpm. The reason is how
wide the screen is. If the document was presented in columns I could read
much faster. I would like to see some discussion on this. I have found
my reading speed improves when there are columns and the scrolling is
horizontal instead of vertical.
I think the use of a table of contents on the left is very important for
quick reference.
Again I think what you have done is good work and I hope more people read
this.
Great observations. Newspapers have used narrow columns for years and books rarely go as wide as today's screens. Many news web sites use tables to set a fixed column width. -DanB
From: Ron Dupas
Date: 6/11/98
Subject: Suggestions
Hi...
Very nice site. I learned a lot just from perusing it, and intend to study
it in more detail as we create a site for our City.
Perhaps this is already covered in your site, but with my user hat on rather
than my designer hat, I am irritated by the very poor job done by many web
site designers on navigation within the site. This seems to be an affliction
of software companies with tech support pages for multiple products and the
use of frames to supposedly aid in navigation.
The average person would try two choices: Click Product, then Support, or
vice versa. In many sites I've tried to use I have gotten into endless loops
trying to find the secret way past the support options into the knoweldge
base. Anything you can do to educate web site designers to think of the user
first in terms of user friendly navigation would be a great benefit to us
all.
Ron Dupas
From: Jeff Silverman
Date: 6/11/98
Subject: Comments on good documents
Jolly good show!
I am a webmaster, and one of the things that irks me no end is people
who just don't get it. I just hosted a site where the page describing
the services rendered by the client was done as a .GIF file. Stupid:
there is no search engine made that can search a .GIF. But the web
site designer picked a font that isn't available on most PCs, so he converted
the prose into an image on his Macintosh and posted it.
At the end of http://www.gooddocuments.com/homepage/about.htm, you write:
"Please send us your comments
This site is not one-way. Send us your comments and suggestions
(there's a mailto
link on the Home Page of the site to comments@gooddocuments.com).
Check the
Mail section to see what others are saying."
There is a mailto: href in there, which is good; but there should also
be an http: href there under Check
the Mail section so that the user can follow the cross reference easily.
Many thanks, and again, keep up the good work. Don't be too apologetic
about making mistakes - you are one of the few people I know of who is
thinking about these questions in a clear and constructive way. Sure,
you will make mistakes, and people will call you on them. That's
good, that's how we learn. Whatever you do, please remember that
we're interested in "what works and what doesn't", not "how does
this product work".
--
Jeff Silverman
I've added the cross-ref as you suggested. Thanks for the comments. -DanB
From: Angela Winter
Date: 6/17/98
Subject: re: good documents
Hi,
I hope to learn a lot by looking at your site in the future; but - I'm
puzzled why the links I've used don't change colour to indicate to me
that I've been there before!! (Especially in the one session).
Possibly, you intend to update the site/links so frequently that nobody
should be discouraged from looking at previously visited sites by a
change in colour (of the links); but, that can be confusing to present
users who have become accustomed to this indicator.
This is an artifact of how I set up using Trellix 1.0 for writing this site. When I redo the layout later this summer I plan to make the visited links colors more appropriate and consistent. Right now, on some pages they are the same as the link color, on others they are black like the text and the unread links are blue, and on yet others everything is black..., all depending on my whim at the time of writing. Sorry. -DanB