Messages in this thread |  | | Date | Wed, 04 Dec 2013 19:35:19 -0600 | From | Rob Landley <> | Subject | Re: [PATCH v2] Documentation: gpiolib: document new interface |
| |
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
|  |