Re: [RFC] Documentation dir is a mess

From: Marc Koschewski (marc_at_osknowledge.org)
Date: 11/22/05

  • Next message: Tarkan Erimer: "Re: what is our answer to ZFS?" 
    Date:	Tue, 22 Nov 2005 10:56:39 +0100
To: Matthew Frost <artusemrys@sbcglobal.net>

    * Matthew Frost <artusemrys@sbcglobal.net> [2005-11-21 22:06:48 -0800]:

    > --- Marc Koschewski <marc@osknowledge.org> wrote:
    >
    > > * Steven Rostedt <rostedt@goodmis.org> [2005-11-20 20:56:59 -0500]:
    > >
    > > > On Sun, 2005-11-20 at 16:30 -0800, Greg KH wrote:
    > > > > On Sun, Nov 20, 2005 at 01:19:09PM +0100, Xose Vazquez Perez wrote:
    > > > > > hi,
    > > > > >
    > > > > > _today_ Documentation/* is a mess of files. It would be good
    > > > > > to have the _same_ tree as the code has:
    > > > >
    > > > > Do you have a proposal as to what specific files in that directory
    > > > > should go where? Just basing it on the source tree will not get
    > > > > you very far...
    > > >
    > > > Actually I think it's a good start. When I'm looking for
    > > > documentation, I usually just do a grep -r on the Documentation
    > > > directory hoping I get a correct hit and then manually look
    > > > through all the results I get.
    > > > It does get tedious, and I miss things all the time.
    > >
    > > As you're just about to maybe make a decision on reorganisation: how
    > > about a separation of user- and developer-relevant documentation?
    > > I mean, kernel boot parameters are relevant to a user whereas
    > > mm/* stuff is not.
    >
    > There's a problem in the general conception that user/developer is a
    > mutex. The whole idea is that anyone may become a developer at will. A
    > division of Documentation/ to make an artificial distinction that the
    > community doesn't necessarily believe in doesn't seem too useful.

    Sure, a developer is always a user. But even if so, we could, however,
    split some docs into a developer and an end-user part. Configuring
    PCMCIA doesn't mean I wanted to be 'bothered' by some internals of the
    implementation.

    What about a such an approach?

    Documentation/howto/.../...
    Documentation/howto/pcmcia/...
    Documentation/howto/.../...
    Documentation/dev/...
    Documentation/dev/pcmcia/...
    Documentation/dev/...

    >
    > Now, I don't mean to suggest that you're wrong; I'm sure you have a valid
    > point. If I may rephrase, it sounds more like you're looking for
    > "fingertip reference" versus "in-depth documentation". The documents
    > that exist may not conform themselves well to that sort of division,
    > necessarily. However, I'm sure that there exist fingertip references
    > outside of Documentation/ and the kernel tree; many of them are for
    > 'newbies'.
    >

    Most docs out there one may find through Google or whatever mostly hit
    one particular case. Ie. 'PCMCIA networking device on DELL Inspiron
    8200' and not just a common information on how PCMCIA networking is
    setup in userland.

    Moreover, having such information within the Documentation tree would
    make sense as a user has information on how to _use_ a sub-system right
    when she _enables_ the sub-system (via new kernel installation).

    If the docs would be in a commonly used form (Headlines, prerequisites
    [tools], ...) it would just be a benefit.

    Besides this, it would be nice to reflect the source tree just _a bit_
    within the Documentation tree - ie. create a Documentation/drivers dir
    within information on drivers along with their supported devices in a
    human readable form (no device IDs) and the params the module is able to
    handle. Sure, there's 'modinfo'. But let's have a look ...

    ['sg' is just a common module, no particular reason I took this one]

    marc@stiffy:~$ modinfo sg
    filename: /lib/modules/2.6.15-rc2-marc/kernel/drivers/scsi/sg.ko
    author: Douglas Gilbert
    description: SCSI generic (sg) driver
    license: GPL
    version: 3.5.33
    alias: char-major-21-*
    vermagic: 2.6.15-rc2-marc preempt PENTIUM4 gcc-4.0
    depends: scsi_mod
    srcversion: B8A3D2FFE5BA5BB2348A9AC
    parm: allow_dio:allow direct I/O (default: 0 (disallow)) (int)
    parm: def_reserved_size:size of buffer reserved for each fd
    (int)
    marc@stiffy:~$

    What does a non-developer get out of 'allow direct I/O'?
    - What id direct I/O?
    - How does it affect performance?
    - What are the common pitfalls?
    - Why do I have the choice at all?

    What does a non-developer get out of 'size of buffer reserved for each fd'?
    - What is a buffer?
    - What size is best? Rather small? Rather big? Dependant on my system?
    - What are the common pitfalls?
    - Why do I have the choice at all?

    There are things to answer. And not Google does answer these question.
    Most users (and even more the newbies) are unable to get such
    information out of Google. I know people having PCs (with or without
    Linux) who are unable to get any relevant technical information out of
    Google although they used computers for years now.

    Marc

    > Is this a useful interpretation? Would an incorporation of this sort of
    > functional division meet your request? Does anyone have the time to
    > devote to it? Am I just reading out of the bit bucket?
    >
    > Matt
    -
    To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
    the body of a message to majordomo@vger.kernel.org
    More majordomo info at http://vger.kernel.org/majordomo-info.html
    Please read the FAQ at http://www.tux.org/lkml/

  • Next message: Tarkan Erimer: "Re: what is our answer to ZFS?"

    Relevant Pages

    • Re: Privacy should be the topic here, not privacy.li (from a privacy.li advocate)
      ... The trolls you talk about have a few things in common, ... services web sites nearly verbatim. ... how can you lay any claim to being an anonymizing service? ... Google it, I think it was me that gave an answer about 2 weeks ago. ...
      (alt.privacy)
    • Re: Cheaters
      ... It is actually quite common ... I very much doubt that a generic glitch at Google would ... posts you made within a small time-frame were all sent to one machine ... conclusion that I would jump to if the same events happened to me. ...
      (comp.lang.java.programmer)
    • Re: what kept you?
      ... more common than "What was keeping you?" ... Google searches don't justify more quantitative conclusions, ... a lot of these problems (not the OCR errors!) by using Google Book ... at tpg dot com dot au ...
      (alt.usage.english)
    • Re: Cheaters
      ... It is actually quite common ... you have only seen a hick-up in Google Groups' implementation of ... I very much doubt that a generic glitch at Google would ... It is possible that they use some sort of session affinity as well, so that a user is more likely to reach the same cluster node repeatedly. ...
      (comp.lang.java.programmer)