OSDL to fund a kernel tech writer

[Posted November 7, 2006 by corbet]

From:		Sharon Smith <linuxpr-AT-yahoo.com>
To:		linuxpr-AT-yahoo.com
Subject:		News Item: OSDL Tags Fellowship Fund Donations for Linux Kernel Documentation
Date:		Tue, 7 Nov 2006 04:43:19 -0800 (PST)

   
  OSDL Tags Fellowship Fund Donations for Linux Kernel Documentation
  OSDL fellowship will fill the gap for a long-awaited technical writer for
Linux kernel
  BEAVERTON, Ore., November 7, 2006 - The Open Source Development Labs
(OSDL), a global consortium dedicated to accelerating the adoption of Linux®
and open source software, today announced the first fellowship grant from its
Fellowship Fund announced earlier this year. The one-year fellowship grant
will sponsor a technical writer, whose work will be targeted at Linux kernel
documentation, further accelerating and maximizing Linux development.
  ÂThe OSDL Fellowship Fund was created to meet the unfulfilled needs of
Linux and open source software developers and provide resources to projects
not funded or naturally sourced by the community development model,Â said
Stuart Cohen, CEO of OSDL. ÂWeÂre happy to see Linux kernel documentation
be the first project funded because it aligns with the FundÂs purpose to
fill unnecessary gaps and gives Linux users even greater confidence in the
products they are buying.Â
  The fellowship position for a Linux kernel technical writer has been posted
at
https://www.osdl.org/about_osdl/jobs/linux-kernel-documen....
The contract position will include maintaining the documentation directory in
the Linux kernel source tree with an emphasis on keeping current
documentation up to date, creating new documentation and creating and
maintaining tools such as kerneldoc scripts and Makefiles. The addition of
this position will increase Linux kernel community collaboration by keeping
documentation current and supplementing information that may be lacking. 
  The OSDL Fellowship Fund was established in March and has received public
contributions from Google and HP. The OSDL board of directors, with input
from the Technical Advisory Board (TAB), evaluates applications for
fellowship funding and determines allocation priorities and levels of
financial commitment. The TAB, an OSDL advisory board comprised of leading
Linux and open source software developers, conducted new board elections at
the Ottawa Linux Symposium (OLS) in July. Andrew Morton, Linux developer for
Google and Linux kernel maintainer, is the TABÂs newest member.   
  "Linux kernel documentation is an area where the community has long voiced
its desire for improvement, which the Fellowship Fund now makes it possible
to address. Documentation is key to attracting new developers to Linux and
easing the barriers to maintenance of the existing code. This fellowship will
enable the recipient to improve the existing documentation via cooperation
with the Linux community,Â said James Bottomley, chair of the OSDL TAB and
CTO at SteelEye.
  OSDL will continue to accept pledges and secure financial support for the
fund. For more information on how to donate to the Fellowship Fund or to
apply for fellowship funding, please visit
http://www.osdl.org/lab_activities/fellowship_fund/.
  About Open Source Development Labs (OSDL)
  OSDL Â sponsor of Linus Torvalds, the creator of the Linux kernel and
other key Linux developers - is dedicated to accelerating the growth and
adoption of Linux-based operating systems in the enterprise. Founded in 2000
and supported by a global consortium of major Linux customers and IT industry
leaders, OSDL is a nonprofit organization that provides state-of-the-art
computing and test facilities available to developers around the world. With
offices in China, Japan and the United States, OSDL sponsors legal and
development projects to advance open source software as well as initiatives
for Linux systems in telecommunications, in the data center and on enterprise
desktops. Visit OSDL on the Web at www.osdl.org.
  OSDL is a trademark of Open Source Development Labs, Inc. Linux is a
trademark of Linus Torvalds. Third party marks and brands are the property of
their respective holders.
  ###

OSDL to fund a kernel tech writer

Posted Nov 7, 2006 15:11 UTC (Tue) by cantsin (guest, #4420) [Link] (9 responses)

Who could be a better candidate for that job than Jon Corbet?

OSDL to fund a kernel tech writer

Posted Nov 7, 2006 15:40 UTC (Tue) by Los__D (guest, #15263) [Link] (4 responses)

(Shhhh, don't give him any good ideas, we need him here!) ;)

OSDL to fund a kernel tech writer

Posted Nov 7, 2006 16:51 UTC (Tue) by pointwood (guest, #2814) [Link]

Agreed! I would hate to loose lwn.net!

Part time!

Posted Nov 7, 2006 20:53 UTC (Tue) by felixfix (subscriber, #242) [Link] (1 responses)

Jeez, if OSDL had half a brain they'd fund Jon part time at least.

Now whether Jon would take it ... I will avoid any half brain jokes there because I suspect Jon knows more inside scoop on OSDL than we do, and might not want to say much publicly.

Part time!

Posted Nov 9, 2006 17:03 UTC (Thu) by iabervon (subscriber, #722) [Link]

I think I remember an announcement a while back that OSDL was getting a corporate subscription to LWN. That would be the sensible way for them to fund Jon, since it helps to keep his day job going. Keeping LWN afloat means subscribers keep contribution which nets Jon more in the long run than OSDL is likely to fund him directly.

OSDL to fund a kernel tech writer

Posted Nov 7, 2006 22:14 UTC (Tue) by csawtell (guest, #986) [Link]

There is no need to fear that LWN will lose Mr. Corbet. While the job
description calls for fluency in the C programming language, it does not
require fluency in written English. Therefore Jon is overqualified and
won't be offered the job. Thus we can rest assured that we won't be
deprived of Our Editor, and the /Documentation tree will be vastly
expanded with many kilobytes of semi-literate geek-speek. OK it's a
cynical joust, but I hope people will accept that it is more than half in
jest.

OSDL to fund a kernel tech writer

Posted Nov 7, 2006 16:32 UTC (Tue) by rfunk (subscriber, #4054) [Link]

Yeah, I expected the last sentence of the front-page blurb to say that
Jon had accepted the position.

OSDL to fund a kernel tech writer

Posted Nov 7, 2006 17:32 UTC (Tue) by iabervon (subscriber, #722) [Link]

I think hiring Jon would be excluded by the desire to use fellowship positions to increase the number of people who are doing this stuff for a living.

OSDL to fund a kernel tech writer

Posted Nov 8, 2006 1:42 UTC (Wed) by aya (guest, #19767) [Link]

Mel Gorman (aka the guy who wrote the Linux 2.4 VM documentation) came to mind, actually. (No offense to Jon :3 ) Except that he's not looking for a job right now, apparently.

Not applying

Posted Nov 8, 2006 17:20 UTC (Wed) by corbet (editor, #1) [Link]

Just in case anybody is really wondering: I am not applying for this position. LWN keeps me busy enough writing, so I prefer that any outside endeavors involve code...

OSDL to fund a kernel tech writer

Posted Nov 7, 2006 17:29 UTC (Tue) by donbarry (guest, #10485) [Link] (5 responses)

John's introductory blurb implied monies were hard to find. Yet OSDL seems awash in cash -- consulting guidestar.org gives the 2004 IRS form 990 -- They had about $8.2 million in revenues that year and paid out $5 million in wages directly. So far so good. But Stuart Cohen, as CEO, took $507,278 of that.

Should we really support any 501(c) type organization which pays anyone such a rich salary? At a fairer tax-exempt wage, OSDL could support *multiple* tech writers.

Let's outsource Stuart Cohen's management job to the third world for a competitive wage.

(compare remuneration for directors at the Apache Foundation, etc. Typically a factor of four less.)

(disclaimer: I don't know Stuart and he's probably a fine fellow personally -- and OSDL has done some pretty good deeds. But I object on principle to this sort of wage in a tax-exempt organization.)

OSDL to fund a kernel tech writer

Posted Nov 7, 2006 21:43 UTC (Tue) by s_cargo (guest, #10473) [Link] (4 responses)

If those that contribute funds consider his salary excessive, they can either say so or contribute less. If they think he's worth it, so be it.

If you think you can do the same or better job for less pay, then submit your resume.

OSDL to fund a kernel tech writer

Posted Nov 7, 2006 22:10 UTC (Tue) by Zack (guest, #37335) [Link] (3 responses)

If this were a commercial entity there would be no problem. But I fail to see how (as this entity purports to be part of a community where rewards are based on merit) blowing half a million dolllars on a single person can be warranted.

Perhaps the push to ridicule GNU/Linux and just call it "Linux" is indeed really practical, just in very a business sense way.

OSDL to fund a kernel tech writer

Posted Nov 8, 2006 19:36 UTC (Wed) by eklitzke (subscriber, #36426) [Link] (2 responses)

The OSDL is run like a business, just like nearly every other NPO in America. They are competing against wealthy commercial companies like Microsoft and Sun to promote open source software. To compete in that kind of environment, they need to attract the best people possible, and sometimes that means paying large salaries.

I'm sure they could find someone willing to run the OSDL for less pay, but I doubt that person would be as experienced or effective at doing what Stuart Cohen does -- pushing Linux in business, academia, etc.

OSDL to fund a kernel tech writer

Posted Nov 8, 2006 20:38 UTC (Wed) by Zack (guest, #37335) [Link] (1 responses)

>To compete in that kind of environment, they need to attract the best people possible,

They already did, you can find them on LKML and various mailing lists around the world

I'm sorry:
"OSDL fellowship will fill the gap for a long-awaited technical writer for
Linux kernel" is just too much irony here. They could have it documented in Swahili by now.

If I was in this to feed the fat cats I would send my cheques directly to Ballmer. At least he gets up on stage and dances for his money.

OSDL to fund a kernel tech writer

Posted Nov 9, 2006 3:34 UTC (Thu) by dlang (guest, #313) [Link]

so don't donate any money to OSDL if you feel that they are just fat cats out to absorb your money.

but the fact is that the l-k list and all the other mailing lists have not attracted sufficant interest from people who are good at writing documentation. this is why OSDL is going to pay someone to work on this full time.

documentation is one of those jobs that needs to be done, but very few people find it fun (at least not as fun as other things that they can do), so when you have a job that needs doing, and the fun of doing it isn't enough compensation, then the solution is to pay someone to do the job and add money to the compensation side of the ledger.

accordeing to Andrew Morton OSDL has also expressed interest in paying someone to do the thankless job of tracking known bugs and regressions, and trying to get the maintainers/developers of that area to address them (this is something that Andrew does himself from time to time. everyone agrees that the kernel would be better if it was done more, but Andrew has other things to do). This is another job that nobody has voluntered for in the last 15 years of development.

OSDL to fund a kernel tech writer

Posted Nov 8, 2006 18:43 UTC (Wed) by MisterIO (guest, #36192) [Link] (8 responses)

Whoever is going to take that job should have as his 1st priority to add more examples to the linux kernel.IMHO this is one of the biggest problem of linux's docs,it lacks examples of coding drivers and core kernel components.The linux kernel books are not really better at that,except for the linux drivers book,but it goes too quickly out of date with the kernel!And this site too,that is the best site about Linux on the Net,should have code examples,real code examples,and not only updates of the kernel api and the kernel structure.

Examples? The whole thing is an example!

Posted Nov 9, 2006 6:56 UTC (Thu) by xoddam (guest, #2322) [Link] (4 responses)

> it lacks examples of coding drivers and core kernel components.

WTF? *Every* driver is an example driver!!!!

> this site too,that is the best site about Linux on the Net,
> should have code examples,real code examples,
> and not only updates of the kernel api and the kernel structure.

Really, the place for the example code is LKML. LWN is excellent at
linking to the relevant patches in the list archives.

It's Free Software dude, the whole thing is the example!

Examples? The whole thing is an example!

Posted Nov 9, 2006 16:47 UTC (Thu) by iabervon (subscriber, #722) [Link] (3 responses)

Actual drivers are notoriously full of things that seemed like a good idea when they were written, but we know better now, and things that weren't even good at the time, but nobody looked too closely. It would be useful to have *good* example drivers. (And, of course, a maintainer for them, because example drivers are even more likely to stick with out-of-date practices, since they don't get thoroughly tested and updated, due to not actually doing anything.)

Examples? The whole thing is an example!

Posted Nov 9, 2006 22:57 UTC (Thu) by k8to (guest, #15413) [Link] (2 responses)

I was about to make the point that example drivers are always even worse, and then you made it for me.

It would be great if somone was hard at working crafting and maintaining code and text designed to show people the ropes of kernel work, but that someone had better lean as heavily as possible on existing known-to-minimize errors techniques.

Examples? The whole thing is an example!

Posted Nov 10, 2006 1:13 UTC (Fri) by xoddam (guest, #2322) [Link] (1 responses)

The best we can possibly do in this department is to maintain working
code properly and update it to conform with best practice. As far as I'm
aware this is exactly the job that most kernel developers already do.

Sure, not every part of the kernel is up-to-the-minute. But I promise
you that code which is used by millions of people and looked after by
several responsive developers is in better shape than any dusty 'example'
on a website or in a book that doesn't push bits around for the general
public.

Examples? The whole thing is an example!

Posted Nov 10, 2006 20:19 UTC (Fri) by rgoates (guest, #3280) [Link]

How about designating specific drivers and other pieces of kernel code as examples worth emulating? Kernel hackers and driver writers can discuss/argue the merits and come to some decision about which pieces of code most deserve to be examples. I personally would greatly appreciate having such direction.

OSDL to fund a kernel tech writer

Posted Nov 9, 2006 15:54 UTC (Thu) by riel (subscriber, #3142) [Link] (1 responses)

There is some kernel documentation on the Kernel Newbies site, but if you have ideas for additional content I would be interested in hearing them.

Also, the content on the Kernel Newbies site is available under a creative commons license, and can be used as part of other documentation. The goal is to teach as many people as possible. If you have contributions to make, you can create yourself a login and help editing any time, since kernelnewbies.org is a wiki.

OSDL to fund a kernel tech writer

Posted Nov 10, 2006 18:38 UTC (Fri) by MisterIO (guest, #36192) [Link]

Yeah,I know there's kernelnewbies,there's kerneltrap,there was kerneltraffic,so why there's a Documentation folder in the Linux tree?Take it away if it's so useless there!And production code isn't good example code.Example code should be placed in the same folder where there are the documents for the same argument and it should be a focused peace of code,not too small and not too long.And it could be helpful here too!I can't even see why don't you want it?How could it be a problem to have good focused example code in he kernel?And don't tell that you started programming looking at the source code of something like glibc.Everyone starts with something like printf("Hello, world"); and then takes the next step looking at something more complex.The kernel is a really complex peace of code;you can't say : look at it and then start coding.Well you can,but that won't be a good help for newbies and kerneljanitors is not really better.It's mostly a way for kernel developers to leave to others the boring work!Anyway maybe I'm wrong,but this is what I think!

OSDL to fund a kernel tech writer

Posted Nov 12, 2006 15:27 UTC (Sun) by Blaisorblade (guest, #25465) [Link]

> The linux kernel books are not really better at that,except for the
> linux drivers book,but it goes too quickly out of date with the kernel!

I've had problems even at using a Linux driver book, namely Linux Device Drivers. Maybe I'm off topic since this is too detailed, but I couldn't explain myself without examples - I would have needed much more time to write this post).

I was not trying to write a driver from scratch, but to remove excess locking (which was doing harm) from an existing driver (arch/um/drivers/net_kern.c: uml_net_open in 2.6.18 is one offending place, with
spin_lock(&lp->lock);
...
um_request_irq(...) /* a request_irq wrapper, allocates memory with GFP_KERNEL*/
...
spin_unlock(&lp->lock);
).

In LDD3 examples there is no lock protecting against multiple concurrent open and/or close operations, which is correct, but there is also no explaination of why it is not needed (there is a complex *undocumented* state machine infrastructure preventing this) - and I've verified that in practice this error happens to other driver authors (in out-of-tree code).

Additionally, the code had to use a spinlock in _open to protect against concurrent ->read and ->write operations (again, not needed for the same reason) - which meant that sleep-inside-spinlock warnings were extremely common.

So, actual bugs were resulting from a lack of documentation.