The Problem with Linux Kernel Documentation, and How We're Fixing It
1–10 of 34 posts
Re: The Problem with Linux Kernel Documentation, and How We're Fixing It
#2Happy to see they pick ReST over MD. ReST is vastly superior for these purposes, in my experience.
Re: The Problem with Linux Kernel Documentation, and How We're Fixing It
#3Related: Tomorrow [29-SEP-2016] afternoon at 15:00-15:40 CET, Jon Corbet of LWN, is giving a talk[1] at Linux Recipes conference in Paris on this subject.
URL[2] to live streaming.
[1] https://kernel-recipes.org/en/2016/talks/kernel-documentatio...
[2] https://air.mozilla.org/kernel-recipes-2016-09-29-PM-Session...
Re: The Problem with Linux Kernel Documentation, and How We're Fixing It
#4Happy to see they pick ReST over MD. ReST is vastly superior for these purposes, in my experience.
Depends. We use Markdown pretty extensively and the drawbacks listed on the site don't really apply - you can always either:
1. Embed HTML (more or less preferred, depending on your situation). 2. Create an extension.
Re: The Problem with Linux Kernel Documentation, and How We're Fixing It
#5The 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.
Re: The Problem with Linux Kernel Documentation, and How We're Fixing It
#6Happy to see they pick ReST over MD. ReST is vastly superior for these purposes, in my experience.
Depends. We use Markdown pretty extensively and the drawbacks listed on the site don't really apply - you can always either: 1. Embed HTML (more or less preferred, depending on your situation). 2. Create an extension.
>Embed HTML (more or less preferred, depending on your situation)
But then you can't embed markdown inside the HTML, like code blocks inside a table. Sure you can use
tags, but then you lose syntax highlighting.Actually I've always wondered why no MD renderer supports something like
which it then treats the same as a ```js
code block. Or a pseudo element...Re: The Problem with Linux Kernel Documentation, and How We're Fixing It
#7The 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.
Re: The Problem with Linux Kernel Documentation, and How We're Fixing It
#8They 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.
Re: The Problem with Linux Kernel Documentation, and How We're Fixing It
#9They should contact the freebsd-doc@ folks.
Re: The Problem with Linux Kernel Documentation, and How We're Fixing It
#10The 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.
Not because of Programmers who think that the time spent writing documentation would be better spent programming some more? ;)