Re: How to document for html and Word -- don't imitate MS's goofs

From: Paul Schmidt (
Date: Sun Feb 02 2003 - 08:42:43 EST

  • Next message: Alan Horkan: "Re: How to document for html and Word -- don't imitate MS's goofs"

    On February 1, 2003 08:12 pm, Jeremiah Foster wrote:
    > Yeah. I agree.
    > On Sat, 2003-02-01 at 18:46, r coyne wrote:
    > > First, your "documentation" essentially consists
    > > entirely of menu trees, i.e., where to find the
    > > command. But the whole point of menus and windowing
    > > shells generally is supposed to be to eliminate or
    > > greatly reduce the need for that sort of thing. *snip*
    > You're right, the GUI should be obvious.
    > > my suggestion is that you need to include *other*
    > > information as well.
    > So I guess you are saying that a how-to should aim for the sweet spot
    > that adds information to intermediate users and explains things to the
    > novice?

    I think the problem is that we tend to write this stuff bass-ackwards in that
    really under save as, the format is more important then the extension, but
    the use is most important. A short description of each format available
    would be most helpful.

    Something like this:

    Save as File Types.

    Abiword (.abw) Abiwords native format, use this when you don't need
    compatability with other software.
    Word (.doc) Microsoft's Word format, suitable when you need compatability
    with Word97 or later.

    and so on .... through all of the supported formats.

    This makes it easier for new users to decide what format they would like to
    use, and removes the complexity of having to remember what type does what.

    > > Which brings us to MS's (and abiword's) second
    > > blunder: The SaveAs dialog is unclear and rather
    > > frightening because it confuses and conflates two
    > > totally separate ideas/issues, namely file *type*,
    > > i.e., format, and filename *extension*. What I want
    > > to know is, What will this thing *do* if I click it.
    > > With "save as Word doc" I can sort of guess, because I
    > > know that Word and abi each have a whole bunch of
    > > internal formatting codes that are not the same, and
    > > presumably what I get is a file that uses the Word
    > > codes to correspond to and thus produce in Word a
    > > document that looks more or less the same as the abi
    > > one. But what does it *mean* to "save as HTML"? An
    > > HTML document/file simply *is* text. So will Save As
    > > HTML simply strip out all the abw complexities to
    > > produce straight, old-fashioned text and then tack
    > > ".html" on the end of my specified filename? Or will
    > > it try to translate the abi formatting codes into HTML
    > > formatting tags so as to make it look alike in a
    > > browser, as for the Word case? But that's only
    > > layout; what about links? Will anything that looks
    > > like an Internet address be duplicated (and expanded
    > > into a full URL) in a HTML tag to make it function as
    > > an active link in the HTML document? That's the sort
    > > of thing Yahoo news does, and it's often stupidly
    > > inappropriate and annoying; does abi do it better?
    > > And if there are images and frames and the like in the
    > > abi document, the sorts of things that HTML does by
    > > referring to separate files, will such files be
    > > generated? Where will they be put and what will they
    > > be called?
    > I will try to cover some of this stuff.
    > > you should tell us *something*, enough to give me a
    > > basic, sketchy understanding of what's about to
    > > happen, so that I can figure out whether it's what I
    > > want and whether it's safe and what I'll need to do
    > > later. Without that much, I am left feeling I don't
    > > dare click anything, because who knows what it might
    > Yeah, I agree, and that is what makes a good how to hard when you have a
    > program with so many options. If you just want to burn a data CD, the
    > how-to can be a complete reference. A program like AbiWord has so many
    > potential how-tos
    > > And -- especially since you do offer this
    > > in hypertext format -- you should include a full set
    > > of references/links to the complete documentation, for
    > > those who want more info.
    > I should link to the documentation. I am unsure why I did not do this.
    > Thanks for the feedback.
    > + Jeremiah
    > -----------------------------------------------
    > To unsubscribe from this list, send a message to
    > with the word
    > unsubscribe in the message body.
    To unsubscribe from this list, send a message to with the word
    unsubscribe in the message body.

    This archive was generated by hypermail 2.1.4 : Sun Feb 02 2003 - 10:50:04 EST