Message-ID: <87lhandhya.fsf@notabene.neil.brown.name>
Date:	Wed, 28 Oct 2015 08:12:29 +0900
From:	Neil Brown <neil@...wn.name>
To:	"J. Bruce Fields" <bfields@...ldses.org>
Cc:	Jonathan Corbet <corbet@....net>,
	Randy Dunlap <rdunlap@...radead.org>,
	Al Viro <viro@...IV.linux.org.uk>,
	lkml <linux-kernel@...r.kernel.org>, linux-doc@...r.kernel.org
Subject: Re: [PATCHv2] Documentation: add new description of path-name lookup.

On Wed, Oct 28 2015, J. Bruce Fields wrote:

> On Mon, Oct 26, 2015 at 03:35:54PM +0900, Neil Brown wrote:
>> From c38784b876a181eda9a5687e618749157dc96a0e Mon Sep 17 00:00:00 2001
>> From: NeilBrown <neil@...wn.name>
>> Date: Sat, 25 Jul 2015 10:24:41 +1000
>> Subject: [PATCH] Documentation: add new description of path-name lookup.
>> 
>> This document is based on three recent lwn.net articles.
>> Some of the introductory material and linkage between articles
>> has been removed, and some time-based descriptions have been
>> revised.
>
> Thanks for doing this!  Nit:
>
>> +End of the road
>> +---------------
>> +
>> +Despite its complexity, all this pathname lookup code appears to be
>> +in good shape - various parts are certainly easier to understand now
>> +than even a couple of releases ago.  But that doesn't mean it is
>> +"finished".   As already mentioned, RCU-walk currently only follows
>> +symlinks that are stored in the inode so, while it handles many ext4
>> +symlinks, it doesn't help with NFS, XFS, or Btrfs.  That support
>> +is not likely to be long delayed.
>
> This looks likely to go stale quickly.  Maybe just drop it?
>
> I'd personally also probably drop the introduction.  (I think of
> Documetation/ as reference material with less of a need to tell a
> "story".)  But, I could be wrong.

Allow me to try to convince you that you are wrong :-)

When I want reference material, I look at the code.  Code doesn't get
out of date.
Ideally there should be comments next to lock declarations outlining what
the lock protects, and comments next to function pointer declarations
describing the use and behaviour of that function.  But that sort of
detail - whether as code or comments - should live with the code.

When I go to Documentation/ it is to get the big picture.  To get
answers to the questions that I didn't even know I should ask.  To find
out the "why" and the caveats and the history.  In sort, I want to be
told the story of the particular topic. (Unfortunately, that isn't
usually what I find).

Don't underestimate story.  Story has been the most effective teaching
tool we've had since time immemorial (or so the story goes).  We
disregard it at our peril.

I've had a couple of experiences recently that reflect on the teaching
of mathematics, one concerning trigonometry

  https://plus.google.com/+LinusTorvalds/posts/Y6i9Mnk3sno

and one concerning quadratic equations.  Both cases could be viewed as
an over emphasis on specific details (important though they are) without
enough time being spent on the big-picture story of why these things are
*everywhere*.

There is certainly value in structuring the story so that a reader can
come back and easily find the detail they need to be reminded about.
But that first time, when you have no idea how things work, but need to
fix a bug or understand why you cannot find a way to add that feature
you so desperately need, having a story to read (and the patience to
read it) can be a big help.

NeilBrown

Download attachment "signature.asc" of type "application/pgp-signature" (819 bytes)

Powered by blists - more mailing lists