discuss: Thread: Linux Kernel Module Programming Guide

Hi there,

I'm the author of the Linux Programming Module Guide (LKMPG).  Sadly,
I've let the LKMPG go for a few years.

It wasn't my fault -- I blame the cruel world we live in that requires
us to get a job after school.   I want to atone for my sins, but I'm
not going to go back to docbook; I always hated it and it's the wrong
tool for a living document / moving target / collaborative effort.
There's no reason to use it for a document like the LKMPG, and I'm
fairly confident that the current version of LKMPG in that format is
the last.  I'm done with it.

However, a wiki version of the LKMPG is very intriguing.  It corrects
all the deficiencies of docbook.  It's easy, 100% collaborative, can
be translated into different formats, and easily and quickly
modifiable.   I wouldn't mind putting the LKMPG onto a wiki and going
back to actively maintaining it.   But if I'm going to put in this
kind of time, there's a few things I would like to know first:

1. How do I start?  In other words, where would my top page be?

2. How are foreign translations handled in wiki versions of documents?

3. Can *anyone* modify my pages?  If so, is there a way of restricting
edits to just people with verified accounts on tldp.org?  How is spam
control handled?


Thanks!
Pete

On Wed, Jul 17, 2013 at 4:55 PM, Peter Salzman ####@####.#### wrote:
> Hi there,

Hi!

> I'm the author of the Linux Programming Module Guide (LKMPG).  Sadly,
> I've let the LKMPG go for a few years.

Welcome back :-)

> However, a wiki version of the LKMPG is very intriguing.  It corrects
> all the deficiencies of docbook.  It's easy, 100% collaborative, can
> be translated into different formats, and easily and quickly
> modifiable.   I wouldn't mind putting the LKMPG onto a wiki and going
> back to actively maintaining it.   But if I'm going to put in this
> kind of time, there's a few things I would like to know first:
>
> 1. How do I start?  In other words, where would my top page be?

Just log in and create your top page :)

> 2. How are foreign translations handled in wiki versions of documents?

As any other document, if you find a translator.

> 3. Can *anyone* modify my pages?  If so, is there a way of restricting
> edits to just people with verified accounts on tldp.org?  How is spam
> control handled?

Edits on all pages are restricted to account holders.
Spam is handled by textcha and myself :)

Serge

On Wed, Jul 17, 2013 at 2:46 PM, Sergiusz Pawlowicz
####@####.#### wrote:
> On Wed, Jul 17, 2013 at 4:55 PM, Peter Salzman ####@####.#### wrote:
>> Hi there,
>
> Hi!
>
>> I'm the author of the Linux Programming Module Guide (LKMPG).  Sadly,
>> I've let the LKMPG go for a few years.
>
> Welcome back :-)
>
>> However, a wiki version of the LKMPG is very intriguing.  It corrects
>> all the deficiencies of docbook.  It's easy, 100% collaborative, can
>> be translated into different formats, and easily and quickly
>> modifiable.   I wouldn't mind putting the LKMPG onto a wiki and going
>> back to actively maintaining it.   But if I'm going to put in this
>> kind of time, there's a few things I would like to know first:
>>
>> 1. How do I start?  In other words, where would my top page be?
>
> Just log in and create your top page :)
>
>> 2. How are foreign translations handled in wiki versions of documents?
>
> As any other document, if you find a translator.
>
>> 3. Can *anyone* modify my pages?  If so, is there a way of restricting
>> edits to just people with verified accounts on tldp.org?  How is spam
>> control handled?
>
> Edits on all pages are restricted to account holders.
> Spam is handled by textcha and myself :)
>
> Serge


Thanks for the reply!

I guess all I need to do is think about organization and collect a
posse to start wikifying the LKMPG.  I can handle collecting the
posse, but I'd like to ask for your (and everyone's) suggestion on
organization.  We have quite a few translations, so I was thinking
something along the lines of:

Main Page
|
--- en
|
--- es
|
--- cn
|
--- pt
|
--- (couple of other languages I'm not remembering right now)


Then, under each language, I have two logical choices of organization:

Main Page
|
en
|
--- Chapter 1
|      |
|      --- 2.6
|      |
|      --- 2.8
|      |
|      --- 3.0
|
--- Chapter 2
|      |
|      --- 2.6
|      |
|      --- 2.8

etc.   So that would be a chapter-centric way of organizing the guide.
  As new kernel minor versions come out, I would (or hopefully,
volunteers would) create new kernel version sections underneath each
chapter.   I guess the downside of this is that there might be
"holes," for example, if nobody created Chapter 10 for v3.2.

The other way of organizing it would be kernel-centric:

Main Page
|
en
|
--- 2.6
|      |
|      --- Chap 1
|      |
|      --- Chap 2
|      |
|      --- etc
|
--- 2.8
|      |
|      --- Chap 1
|      |
|      --- Chap 2


Neither organization is obviously better than the other to me.  I can
see pros and cons with each.  In the end it doesn't matter I suppose,
but considering the effort this will take, I want to do the right
thing from the outset.

Does anyone have any gut feelings over whether chapter-centric or
kernel version-centric organization would be better?

Many thanks!
Pete

ps- Please pardon my ascii graphics.  I'm crossing my fingers that
it's comprehensible....

Thanks for asking--it's worthy of some thought!

Off hand, my first thought is that I'd rather see a "chapter centric" 
organization with the latest revision "on top".

Then, as you're reading the document chapter by chapter, if some particular 
section or chapter doesn't have the latest revision, it would seem fairly 
natural to find and read the previous (or some previous) revision.

Randy Kramer

On Thursday 18 July 2013 6:35:26 pm Peter Salzman wrote:
> On Wed, Jul 17, 2013 at 2:46 PM, Sergiusz Pawlowicz
>
> ####@####.#### wrote:
> > On Wed, Jul 17, 2013 at 4:55 PM, Peter Salzman ####@####.#### wrote:
> >> Hi there,
> >
> > Hi!
> >
> >> I'm the author of the Linux Programming Module Guide (LKMPG).  Sadly,
> >> I've let the LKMPG go for a few years.
> >
> > Welcome back :-)
> >
> >> However, a wiki version of the LKMPG is very intriguing.  It corrects
> >> all the deficiencies of docbook.  It's easy, 100% collaborative, can
> >> be translated into different formats, and easily and quickly
> >> modifiable.   I wouldn't mind putting the LKMPG onto a wiki and going
> >> back to actively maintaining it.   But if I'm going to put in this
> >> kind of time, there's a few things I would like to know first:
> >>
> >> 1. How do I start?  In other words, where would my top page be?
> >
> > Just log in and create your top page :)
> >
> >> 2. How are foreign translations handled in wiki versions of documents?
> >
> > As any other document, if you find a translator.
> >
> >> 3. Can *anyone* modify my pages?  If so, is there a way of restricting
> >> edits to just people with verified accounts on tldp.org?  How is spam
> >> control handled?
> >
> > Edits on all pages are restricted to account holders.
> > Spam is handled by textcha and myself :)
> >
> > Serge
>
> Thanks for the reply!
>
> I guess all I need to do is think about organization and collect a
> posse to start wikifying the LKMPG.  I can handle collecting the
> posse, but I'd like to ask for your (and everyone's) suggestion on
> organization.  We have quite a few translations, so I was thinking
> something along the lines of:
>
> Main Page
>
> --- en
>
> --- es
>
> --- cn
>
> --- pt
>
> --- (couple of other languages I'm not remembering right now)
>
>
> Then, under each language, I have two logical choices of organization:
>
> Main Page
>
> en
>
> --- Chapter 1
>
> |      --- 2.6
> |
> |      --- 2.8
> |
> |      --- 3.0
>
> --- Chapter 2
>
> |      --- 2.6
> |
> |      --- 2.8
>
> etc.   So that would be a chapter-centric way of organizing the guide.
>   As new kernel minor versions come out, I would (or hopefully,
> volunteers would) create new kernel version sections underneath each
> chapter.   I guess the downside of this is that there might be
> "holes," for example, if nobody created Chapter 10 for v3.2.
>
> The other way of organizing it would be kernel-centric:
>
> Main Page
>
> en
>
> --- 2.6
>
> |      --- Chap 1
> |
> |      --- Chap 2
> |
> |      --- etc
>
> --- 2.8
>
> |      --- Chap 1
> |
> |      --- Chap 2
>
> Neither organization is obviously better than the other to me.  I can
> see pros and cons with each.  In the end it doesn't matter I suppose,
> but considering the effort this will take, I want to do the right
> thing from the outset.
>
> Does anyone have any gut feelings over whether chapter-centric or
> kernel version-centric organization would be better?
>
> Many thanks!
> Pete
>
> ps- Please pardon my ascii graphics.  I'm crossing my fingers that
> it's comprehensible....
>
> ______________________
> http://lists.tldp.org/

Thanks for the input.  Originally I was planning on kernel centric
organization, but the person who convinced me to get off my butt and
start wikifying the guide suggested the chapter centric organization,
and I'm starting to agree with you guys that it's the way to go.
Seems like there's consensus on this!

Pete




On Thu, Jul 18, 2013 at 11:29 PM, Randy Kramer ####@####.#### wrote:
> Thanks for asking--it's worthy of some thought!
>
> Off hand, my first thought is that I'd rather see a "chapter centric"
> organization with the latest revision "on top".
>
> Then, as you're reading the document chapter by chapter, if some particular
> section or chapter doesn't have the latest revision, it would seem fairly
> natural to find and read the previous (or some previous) revision.
>
> Randy Kramer
>
> On Thursday 18 July 2013 6:35:26 pm Peter Salzman wrote:
>> On Wed, Jul 17, 2013 at 2:46 PM, Sergiusz Pawlowicz
>>
>> ####@####.#### wrote:
>> > On Wed, Jul 17, 2013 at 4:55 PM, Peter Salzman ####@####.#### wrote:
>> >> Hi there,
>> >
>> > Hi!
>> >
>> >> I'm the author of the Linux Programming Module Guide (LKMPG).  Sadly,
>> >> I've let the LKMPG go for a few years.
>> >
>> > Welcome back :-)
>> >
>> >> However, a wiki version of the LKMPG is very intriguing.  It corrects
>> >> all the deficiencies of docbook.  It's easy, 100% collaborative, can
>> >> be translated into different formats, and easily and quickly
>> >> modifiable.   I wouldn't mind putting the LKMPG onto a wiki and going
>> >> back to actively maintaining it.   But if I'm going to put in this
>> >> kind of time, there's a few things I would like to know first:
>> >>
>> >> 1. How do I start?  In other words, where would my top page be?
>> >
>> > Just log in and create your top page :)
>> >
>> >> 2. How are foreign translations handled in wiki versions of documents?
>> >
>> > As any other document, if you find a translator.
>> >
>> >> 3. Can *anyone* modify my pages?  If so, is there a way of restricting
>> >> edits to just people with verified accounts on tldp.org?  How is spam
>> >> control handled?
>> >
>> > Edits on all pages are restricted to account holders.
>> > Spam is handled by textcha and myself :)
>> >
>> > Serge
>>
>> Thanks for the reply!
>>
>> I guess all I need to do is think about organization and collect a
>> posse to start wikifying the LKMPG.  I can handle collecting the
>> posse, but I'd like to ask for your (and everyone's) suggestion on
>> organization.  We have quite a few translations, so I was thinking
>> something along the lines of:
>>
>> Main Page
>>
>> --- en
>>
>> --- es
>>
>> --- cn
>>
>> --- pt
>>
>> --- (couple of other languages I'm not remembering right now)
>>
>>
>> Then, under each language, I have two logical choices of organization:
>>
>> Main Page
>>
>> en
>>
>> --- Chapter 1
>>
>> |      --- 2.6
>> |
>> |      --- 2.8
>> |
>> |      --- 3.0
>>
>> --- Chapter 2
>>
>> |      --- 2.6
>> |
>> |      --- 2.8
>>
>> etc.   So that would be a chapter-centric way of organizing the guide.
>>   As new kernel minor versions come out, I would (or hopefully,
>> volunteers would) create new kernel version sections underneath each
>> chapter.   I guess the downside of this is that there might be
>> "holes," for example, if nobody created Chapter 10 for v3.2.
>>
>> The other way of organizing it would be kernel-centric:
>>
>> Main Page
>>
>> en
>>
>> --- 2.6
>>
>> |      --- Chap 1
>> |
>> |      --- Chap 2
>> |
>> |      --- etc
>>
>> --- 2.8
>>
>> |      --- Chap 1
>> |
>> |      --- Chap 2
>>
>> Neither organization is obviously better than the other to me.  I can
>> see pros and cons with each.  In the end it doesn't matter I suppose,
>> but considering the effort this will take, I want to do the right
>> thing from the outset.
>>
>> Does anyone have any gut feelings over whether chapter-centric or
>> kernel version-centric organization would be better?
>>
>> Many thanks!
>> Pete
>>
>> ps- Please pardon my ascii graphics.  I'm crossing my fingers that
>> it's comprehensible....
>>
>> ______________________
>> http://lists.tldp.org/
>
>
>
> ______________________
> http://lists.tldp.org/
>

Pete,

You're welcome!  

On Thursday 18 July 2013 11:43:33 pm Peter Salzman wrote:
> Thanks for the input.  Originally I was planning on kernel centric
> organization, but the person who convinced me to get off my butt and
> start wikifying the guide suggested the chapter centric organization,
> and I'm starting to agree with you guys that it's the way to go.
> Seems like there's consensus on this!