netdev - Re: critic on documentation of the network stack

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:	Sun, 26 Jan 2014 11:35:13 +0100
From:	Richard Weinberger <richard.weinberger@...il.com>
To:	Florian Fainelli <f.fainelli@...il.com>
Cc:	Stephen Hemminger <stephen@...workplumber.org>,
	Hannes Frederic Sowa <hannes@...essinduktion.org>,
	"netdev@...r.kernel.org" <netdev@...r.kernel.org>
Subject: Re: critic on documentation of the network stack

On Sun, Jan 26, 2014 at 4:18 AM, Florian Fainelli <f.fainelli@...il.com> wrote:
> Le 24/01/2014 15:58, Stephen Hemminger a écrit :
>
>> On Fri, 24 Jan 2014 04:23:24 +0100
>> Hannes Frederic Sowa <hannes@...essinduktion.org> wrote:
>>
>>> Hello!
>>>
>>> After net-next is closed I wanted to put the following link here:
>>>
>>>    <http://linux.slashdot.org/comments.pl?sid=4356053&cid=45184693>
>>
>>
>> The problem I have is more that there are more incorrect sources of
>> documentation
>> and differing opinions on the Internet. Maybe the problem is users, maybe
>> the
>> problem is lack of SEO, or developers not being paid to write
>> documentation, or
>> old web sites not being updated. For example, this commenter obviously
>> never
>> found http://www.lartc.org/
>
>
> (which unfortunately is rather outdated)

s/outdated/dead

> I do not buy the fact that some developers do not provide documentation of
> the features they are adding potentially on purpose, truth is probably much
> simpler, you worked on X, you have now moved on and work on Y.

IMHO one cause of the problem is that many nice features get
implemented by contractors.
The customer is only interested in the kernel interface and has it's
own (proprietary) userland.
Don't get me wrong, this is perfectly fine.
But it has the side effect that a) the customer is not interested in
man-pages or other open docs/tools
(he does not want to reveal his magic sauce too early) and
b) the contractor is therefore not paid to provide docs.

> If nobody pays enough attention to what gets added through netdev, iproute2,
> ethtool, man-pages and enforces the need for documentation, then comes the
> current status quo where not all features are documented, until some
> benevolant person realizes this needs fixing. Considering the high volume of
> the list, this is all understandable.
>
> There could probably be some programmatical ways to enforce such
> documentation by only allowing patches coming with, say kernel-doc content
> along the code, and have man-pages and other projects scan for new
> kernel-doc entries they have no reference for.
> --
> Florian
>
> --
> To unsubscribe from this list: send the line "unsubscribe netdev" in
> the body of a message to majordomo@...r.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html



-- 
Thanks,
//richard
--
To unsubscribe from this list: send the line "unsubscribe netdev" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html