Re: [PATCH v2] Documentation: gpiolib: document new interface

[Rob Landley <rob@landley.net>]

On 11/24/2013 12:02:30 AM, Alexandre Courbot wrote:
> Hi Rob,
> 
> On Sun, Nov 24, 2013 at 8:31 AM, Rob Landley <rob@landley.net> wrote:
> >> > Linus, I hope this can be merged during the -rc cycle of 3.13,  
> since the
> >> > gpiod_ interface is going to be introduced there. It would not  
> make much
> >> > sense for it to come without its documentation.
> >>
> >> You're right of course. I'll read through it and apply fixes on top
> >> (or squash into your patch.)
> >>
> >> Formal stuff:
> >> Don't we need an 00-INDEX file?
> >> (Maybe Rob can tell whether this is desirable.)
> >
> >
> > A 00-INDEX file wouldn't hurt, but it can always be added later. No  
> reason
> > to hold up the series for that. (I was using them to generate html  
> indexes
> > for kernel.org/doc but after the breakin they eliminated all non-git
> > functionality so I haven't been able to update it since. They  
> replaced
> > kernel.org/doc/Documentation with a raw git checkout, and I expect  
> them to
> > replace kernel.org/doc/menuconfig with a raw git checkout any day  
> now.)
> >
> > That said, a 00-INDEX file would let you know where to start  
> reading to find
> > the file with the intro paragraph at the start of the old file, the  
> bit
> > explaining what GPIO is. Here the first file alphabetically is  
> "board.txt",
> > and I have no idea why it's named that, given how it starts. (I was  
> sort of
> > hoping that somebody who already knows the subsystem would comment  
> before I
> > do. I have no way of knowing if this documentation is _right_.)
> 
> I actually submitted a patch that introduces a 00-INDEX file
> yesterday. It's probably a few other gazillions mails under in your
> inbox. ;)

I'm a couple weeks behind on my email. I'll get to it eventually. (My  
time's spread between a few too many projects these days...)

Most documentation goes in through the trees of the people whose  
subsystems it documents. I mostly catch the stuff that falls through  
the cracks. I'm somewhere between a librarian shelving abandoned books  
and a janitor.

...
> > But I really don't have time to go through every paragraph like  
> that, and
> > was hoping the gpio guys would (or just sign off on it so I don't  
> have
> > to)...
> 
> I will make another pass and send an update (or a new version of the
> patch maybe, since we are still in -rc1 - whatever is more convenient
> to Linus). Hopefully early users of the new (oops) interface will send
> fixes to the documentation as well, if only to improve my approximate
> English.

It's not so much the english, it's that Documentation should be aimed  
at people who _don't_ already know this stuff. Since it tends to be  
written by people who _do_ already know the stuff (kinda hard to do the  
other way, although I've done it), this can be tricky to pull off. You  
have to maintain a "But what if this _wasn't_ a rhetorical question?"  
mindset and emulate a Virtual Newbie. (I suggest qemu for this.)

Still, thanks for taking a stab at it. Imperfect's better than  
obsolete...

Rob