LWN: Comments on "Kernel documentation with Sphinx, part 1: how we got here"

Kernel documentation with Sphinx, part 1: how we got here

ortalo — Tue, 19 Jul 2016 16:10:37 +0000

Just a quick ref., cause... I knew the woman who knew the man who... and also cause it seems to me it's worth reading or listening (again).

Sorry for not finding a good link to the full (published) paper but the slides are here: http://fose.ethz.ch/slides/parnas.pdf

and you will find a video around here: https://youtu.be/dn8bVhfAv0c

Kernel documentation with Sphinx, part 1: how we got here

neilbrown — Mon, 18 Jul 2016 21:30:38 +0000

I feel compelled to quote some wise words from a favorite novel by Jane Austen:

"My fingers," said Elizabeth, "do not move over this instrument
in the masterly manner which I see so many women's do. They
have not the same force or rapidity, and do not produce the
same expression. But then I have always supposed it to be my
own fault--because I will not take the trouble of practising.

Kernel documentation with Sphinx, part 1: how we got here

liw — Mon, 18 Jul 2016 18:26:00 +0000

It has, in fact, been my experience that software developers will avoid writing prose longer than a line on IRC. They will got great lengths to avoid it, up to and including standing between decorative bushes of vegetation while wearing camouflage clothing.

It's sad, and not just because it makes those of us who like writing to stand out.

Kernel documentation with Sphinx, part 1: how we got here

jezuch — Mon, 18 Jul 2016 09:07:16 +0000

> I think literate programing can work very well when the programmer fully understands the problem they are trying to solve and can then present it coherently as a lesson to the reader.

Obviously, it also helps if the person writing it all is a good writer. Most of us suck at this :)

Kernel documentation with Sphinx, part 1: how we got here

neilbrown — Mon, 18 Jul 2016 06:58:56 +0000

> So, this is the acceptance of Knuth's concept of literate programming, or are we still not there yet?

long long way from Knuth's literate programming.

LP wasn't just about writing better comments. It also involved changing the order in which code was written so that ideas could be developed in an order that made sense to the human reader, often quite different to the order that the compiler wants.
This isn't just re-arranging function declarations. It might also mean writing a rough outline of a function with various "blanks", then filling in the blanks one by one after explaining them.

I think literate programing can work very well when the programmer fully understands the problem they are trying to solve and can then present it coherently as a lesson to the reader. A lesson which can be compiled and run to show that it works.
I don't think it works well at all for code which is being built by engineers who are coming to understand the problem as they go (most of us) and for whom the requirements change between the start and end of the project (though of course, that would never happen!).

I think that for code that is under development, having significant documentation in with the code is a mistake as it is very likely to become out of date quickly. Having documentation in with the code only makes sense (to me) once the code has stabilized. Then there is at least some chance that the documentation will be vaguely accurate for more than one day.

Certainly some people can make the effort to update documentation whenever they change the code. Both of the people who do that are worth their weight in gold and I respect them. But I doubt I could ever emulate them.

Kernel documentation with Sphinx, part 1: how we got here

sachingarg — Mon, 18 Jul 2016 05:16:35 +0000

So, this is the acceptance of Knuth's concept of literate programming, or are we still not there yet?

Kernel documentation with Sphinx, part 1: how we got here

domo — Thu, 07 Jul 2016 13:07:46 +0000

Thanks Jani, that was good read while pondering between asciidoc & rst (markdown is
usually no-go due to lack of features or standard (i.e. choose either))

Kernel documentation with Sphinx, part 1: how we got here

gwhaley — Wed, 06 Jul 2016 09:07:44 +0000

Having been sat on the periphery of this long running process, and having some understanding of the tangle that had to be unwound and the intricate and many faceted issues that had to be solved - well done all involved! I think we can look forward to a new era of kernel documentation.