Re: Documentation and Usability

From: Micha Feigin (michf_at_post.tau.ac.il)
Date: 01/18/04

  • Next message: David: "Re: Documentation and Usability" 
    Date: Sun, 18 Jan 2004 03:25:04 +0200
To: debian-user@lists.debian.org

    On Sat, Jan 17, 2004 at 01:22:58PM -0700, Monique Y. Herman wrote:
    > On 2004-01-17, Mac McCaskie penned:
    > > I think my point would be closer to not allowing a package on-board
    > > without adaqate instruction on what it was and how to use it.
    > >
    > > Where is the value of providing a widget to a customer without giving
    > > them a clue as to what the widget is or what to do with it.
    > >
    >

    So according to Mac McCaskie if a program writer doesn't bother to
    write the documentation then it shouldn't be packaged until the
    maintainer sits down to write the documentation.
    That approach would keep quite a few programs from being packaged.
    On the other hand if you don't find the documentation supplied with the
    package enough, you can always google for it to find more information
    (I do that quite a bit).
    Considering the fact that the package maintainers volunteer to package
    the programs makes me thankful to them for saving me the work. I am
    always happier if they add documentation where it hasn't existed
    before, but I see it as an extra, not a requirement.

    > That word "customer"; doesn't it imply that you paid for the product?
    >
    > Anyhoo, your definition of adequate might be quite different from
    > another user's definition.
    >
    > If there's a package that will solve a problem for me, I would rather
    > have it available without any documentation at all than have it
    > completely unavailable due to lack of documentation.
    >
    > --
    > monique
    >
    >
    > --
    > To UNSUBSCRIBE, email to debian-user-request@lists.debian.org
    > with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
    > 

    -- 
To UNSUBSCRIBE, email to debian-user-request@lists.debian.org 
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
  • Next message: David: "Re: Documentation and Usability"

    Relevant Pages

    • Re: Finding installed package files
      ... > you appear to want is a file that lists executables and documentation. ... contains links to the most important information about the installation. ... > doubt others could finesse the command. ... I do understand that rpm has many options that tell me about a package. ...
      (alt.os.linux.redhat)
    • Re: Multiple files in a .dtx
      ... a .ins file to extract additional files from a .dtx file (and how to ... I need the package to contain a .sty file and several ... It automatically adds a default preamble and postamble. ... The dtxtut and doctex documentation seems less than forthcoming about ...
      (comp.text.tex)
    • Re: debian how-to
      ... today I wanted to read up on git hook scripts. ... which tells me that git is in the "git-core" package. ... Perhaps it should be policy that if the documentation isn't in the usual ... easily access all the documentation related to a command; PDF viewers ...
      (Debian-User)
    • Re: Javadoc question re Eclipse
      ... The documentation seems to be saying that I should put this file in my source tree under the package being documented. ... I tried creating a Class named package-info in Package Explorer within the ... Each package can have its own package-level doc comment source file that The Javadoc tool will merge into the documentation that it produces. ...
      (comp.lang.java.programmer)
    • Re: debian how-to
      ... today I wanted to read up on git hook scripts. ... because there is no "git" package. ... So I check the source package for git-core to see if the docs got ... I think the biggest problem is that documentation is organized by ...
      (Debian-User)