Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The Problem with Linux Kernel Documentation, and How We're Fixing It

blogs.s-osg.org

Post reply on HN
Print view View original

21–30 of 34 posts

Re: The Problem with Linux Kernel Documentation, and How We're Fixing It

#21

Post by corbet »

proaralyst wrote: post #7
AstralStorm wrote: post #5

The main problem is not the format of the documentation, but lack thereof. Many important functions and high level implementation tasks are not documented or the docs are inadequate.

Perhaps there's little documentation _because_ it has a poor format.

I (being the kernel documentation maintainer) have already seen an increase in activity around the docs as a result of the change - it makes things far more accessible.

It's also not really correct to say there's not much documentation. We have quite a bit if you look at it, especially if you count the 55,000 kerneldoc comments in the source itself. The quality of some of it and the organization of all of it is another matter...but we're working on that.

Re: The Problem with Linux Kernel Documentation, and How We're Fixing It

#22

Post by sqeaky »

proaralyst wrote: post #7
AstralStorm wrote: post #5

The main problem is not the format of the documentation, but lack thereof. Many important functions and high level implementation tasks are not documented or the docs are inadequate.

Perhaps there's little documentation _because_ it has a poor format.

It is almost certainly correct that this is a contributing factor. It is unlikely to be the only factor or even the primary factor.

The very human element, that most programmers simply don't like writing documentation is certainly a larger factor. If this holds true for the Kernel no new format can fix the problem by itself. At a minimum it will require a encouragement from the top to improve.

Re: The Problem with Linux Kernel Documentation, and How We're Fixing It

#24

Post by has2k1 »

Poiesis wrote: post #23
eliben wrote: post #2

Happy to see they pick ReST over MD. ReST is vastly superior for these purposes, in my experience.

Mind explaining why? I like Markdown but would like to know what ReST does better.

ReST can be better extended without creating a variant of the markup language [1]. Extension support is first class [2], and it is by that means that a good number of the core features are implemented.

[1] For example, github flavour, stackoverflow flavour, reddit flavour, ...

[2] Roles and directives.

Re: The Problem with Linux Kernel Documentation, and How We're Fixing It

#25

Post by bduhan »

Sanddancer wrote: post #8

They missed a format that's ubiquitous, has a lot of formatting options, and has search facilities. Manpages. When someone's looking for a piece of documentation, they are usually working on a system as they do it, and man -k is a lot easier to remember than some other search tool that requires its own set of packages, etc.

You can build man pages with Sphinx.

http://www.sphinx-doc.org/en/stable/builders.html

Re: The Problem with Linux Kernel Documentation, and How We're Fixing It

#26

Post by Sanddancer »

dend wrote: post #17
Sanddancer wrote: post #8

They missed a format that's ubiquitous, has a lot of formatting options, and has search facilities. Manpages. When someone's looking for a piece of documentation, they are usually working on a system as they do it, and man -k is a lot easier to remember than some other search tool that requires its own set of packages, etc.

The problem with that approach is that you are limiting yourself to fundamentally primitive documentation (and by primitive I mean non-interactive). Granted, for a kernel it might be less important, but it's great when there is a good architecture diagram/image instead of 7 paragraphs.

Manpages can have a rather large amount of interactivity. Documents can be formatted as text, as HTML, with links, etc. The problem is that manpages are an afterthought in too much of the Linux ecosystem, so people have low expectations and low beliefs in what they can actually do. They can have tables, they can have equations, they can have graphics.

Re: The Problem with Linux Kernel Documentation, and How We're Fixing It

#27

Post by dend »

Sanddancer wrote: post #26
dend wrote: post #17

Earlier quoted context omitted.

The problem with that approach is that you are limiting yourself to fundamentally primitive documentation (and by primitive I mean non-interactive). Granted, for a kernel it might be less important, but it's great when there is a good architecture diagram/image instead of 7 paragraphs.

Manpages can have a rather large amount of interactivity. Documents can be formatted as text, as HTML, with links, etc. The problem is that manpages are an afterthought in too much of the Linux ecosystem, so people have low expectations and low beliefs in what they can actually do. They can have tables, they can have equations, they can have graphics.

Out of genuine curiosity, could you link me to an existing guide from the Linux community that is based on manpages and features images and/or other interactive content?

Re: The Problem with Linux Kernel Documentation, and How We're Fixing It

#28

Post by sohkamyung »

I find it surprising that Michael Kerrisk's Linux man-pages project isn't mentioned here [1]. He and other contributors done a major job documenting the Linux man pages. It's usually the first place I go to when I need to read up on the Kernel APIs or C libraries.

- [1] https://www.kernel.org/doc/man-pages/

Re: The Problem with Linux Kernel Documentation, and How We're Fixing It

#29

Post by jap »

dend wrote: post #27
Sanddancer wrote: post #26

Earlier quoted context omitted.

Manpages can have a rather large amount of interactivity. Documents can be formatted as text, as HTML, with links, etc. The problem is that manpages are an afterthought in too much of the Linux ecosystem, so people have low expectations and low beliefs in what they can actually do. They can have tables, they can have equations, they can have graphics.

Out of genuine curiosity, could you link me to an existing guide from the Linux community that is based on manpages and features images and/or other interactive content?

Not exhaustive, but I've written code that processes 50,000 or so man pages and haven't hit one.
Post reply on HN