Re: [RFC] Documentation dir is a mess

From: Matthew Frost (artusemrys_at_sbcglobal.net)
Date: 11/22/05

  • Next message: Pierre Ossman: "Re: [RFC] Secure Digital Host Controller PCI class" 
    Date:	Mon, 21 Nov 2005 22:06:48 -0800 (PST)
To: Marc Koschewski <marc@osknowledge.org>, Steven Rostedt <rostedt@goodmis.org>

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

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

    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

    >
    > Marc
    > -
    > 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/
    >

    -
    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: Pierre Ossman: "Re: [RFC] Secure Digital Host Controller PCI class"

    Relevant Pages

    • Re: ISO electronic versions of A2 tech docs
      ... Documentation ... GS-24 MPW-IIGS ORCA:C ... Beep ... Sort ...
      (comp.sys.apple2)
    • tamely research this vocational medicine
      ... Otherwise the assertion in Ismat's documentation might eat some ... regulatory threats. ... toss random currents sort of Pervez's queue. ... Others comparatively compare. ...
      (sci.crypt)
    • Re: [PATCH - EXPERIMENTAL] files with forks in the VFS
      ... an icon for a desktop app, documentation ... >In the first case, the subordinate files should clearly be writable, ... directory compression plugin for directories with lots of small files.... ... send the line "unsubscribe linux-kernel" in ...
      (Linux-Kernel)
    • Re: perl and the culture of libraries
      ... A very high bar for us nerdy anti-social shmoes who usually have trouble ... is the sort of thing that we should be aiming towards. ... documentation in Ruby at all. ... I would like to address - rdoc is too tied into the code, ...
      (comp.lang.ruby)
    • Re: MacTeX 2007 and documentation
      ... who wish to write documentation rather than keeping themselves hidden ... Naturally - no other sort of person can do the job. ... And you damned well know that - so what we have here is dishonest ... Repeating the same complaints again and again, ...
      (comp.text.tex)