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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxxxx> 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--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html




[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux