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

From: Jeremiah Foster (
Date: Sat Feb 01 2003 - 20:12:15 EST

  • Next message: Jim Hettmer: "Kudos and re: don't imitate MS's goofs"

    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

    > 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.

    This archive was generated by hypermail 2.1.4 : Sat Feb 01 2003 - 20:13:29 EST