Re: Documentation (Was: Re: [1.2 installation]: how to tell X to ...)
> From: Fabien Ninoles <ninf01@castor.gel.usherb.ca>
> On Tue, 14 Jan 1997, Daniel S. Barclay wrote:
>
> > However, how are users supposed to find out about those things?
> > (Not to say your suggestion is bad, but to address how to make that
> > information easier to find.)
>
> What about a "Tip of the day" package in place of fortune
> (just kidding ;)
Good. :-) I HATE that "feature" of Windows 95. (I want a f**cking manual
so I can look up what I need now and/or so I can read whole sections and know
I know how to do whatever comes up in the future, without having to wait
for random tip selection to have covered everything in the tips list--which
is pretty short anyway.)
Oh...yeah; sorry. Okay.
#undef HATE_MICROSOFT_MODE
> >
> > Several comments / suggestions / questions / other ramblings, some directly
> > on this, and some on documentation more generally:
> >
> > 1. I wish more old things pointed to new things (new things that replace or
> > just enhance them), especially in manual pages (or wherever we think
> > users usually look for definitive documentation).
> >
> > (You can find out you're doing things the wrong way or an old way
> > by mentioning it on a mailing list, but that knowledge (from people
> > who know about newer things) doesn't get captured in the written
> > documentation as much as it might.)
>
> That's why Archive Mailing List are for. Did you suggest we should packed
> it for local use and search?
No, I wasn't suggesting that.
Hmm. No, I don't think I'd want that--too much to search through and I don't
think you could search it very reliably.
>
> > I know a new package can't modify an existing manual page
> > (especially when you haven't even loaded the package on your system
> > yet), but...
> >
> > 2. ...maybe creators and maintainers of new packages could ask maintainers
> > (at least of documentation) of older packages to add links to the
> > manual pages (etc.)
>
> I didn't undrestand your point here.
If command "old_simple_x" is superseded by "new_fancy_x", then ideally
the documentation for old_simple_x that a user might run into (e.g., the
manual page) would say "don't forget that now there is new_fancy_x you might
want to use instead."
I _have_ seen that on a few Unix manual pages or somewhere similar (maybe
GNU info pages for the C library, documenting routines that still exist
but for which better replacements exist.)
Obviously, not much of this is going to happen, at least not in internal
documentation.
Some documents, such as the HOWTO documents, do get updated a while.
Maybe something based on or connected to them would be good.
> > 3. Keep in mind that it's hard to keep up with constantly-changing
> > documentation. That is, a new user probably would read all
> > the HOWTOs, README files, etc., to get started, but after that,
> > it's impossible to re-read everything just to find the changes.
> >
> > I would think that direct-lookup on-line documentation like manual
> > pages or GNU info pages would be used on a continuing basis, so
> > I would hope that all new information would make it into that
> > reference documentation, and hopefully a few pointers to new,
> > alternative, or add-on things could be included too.
>
> That's why Changelogs exists.
I'm trying to find a way to consolidate the information. If I read a
manual page for something, then I also have to check the /usr/doc
directory...and any GNU info pages...and then I have to get the source
package to check the ChangeLog (or are ChangeLogs included in binary
Debian packages).
That remind me of another documentation problem resulting from not thinking
about how the software is installed:
The diald manual page refers the reader to diald.h. Now why should I have
download and install the diald source package just to learn which bits
get which debugging information? Not a big or stupid mistake or anything,
but it appears that the author was only thinking of the case in which
users build diald themselves, and have the source code lying around.
If we thought a little bit more about what we're doing...
(I've seen a number of cases of little things that could have been
better with just a little thought.)
(Is there any documentation policy document, either for Debian or for
Linux generally, to which I should contribute any useful ideas I might
have?)
> >
> > Oh...whatever.
>
> Nevermind! Debian, IMNSHO, has one of the best documentation of all
> Debian Distribution cause we make more than just put the docs from each
> package, we corrected them and add to them.
>
> But criticizing help us (the maintainers) to make a better distribution.
> Just don't forget to be polite and patient (We are only volunteers).
> If you can wait, put your hands on then!
Wait! That "whatever" was about whatever other thoughts I had that weren't
clear or which I couldn't get written down--not about Debian.
Daniel
--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-user-REQUEST@lists.debian.org . Trouble? e-mail to Bruce@Pixar.com
Reply to: