linux-kernel - Documentation/index.rst

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-next>] [day] [month] [year] [list]

Message-ID: <YlPps05WaHH2ghmp@zn.tnic>
Date:   Mon, 11 Apr 2022 10:41:23 +0200
From:   Borislav Petkov <bp@...en8.de>
To:     Jonathan Corbet <corbet@....net>
Cc:     linux-doc@...r.kernel.org, lkml <linux-kernel@...r.kernel.org>
Subject: Documentation/index.rst

Hey Jon,

so this has been irking me for some time now:

I'd build html documentation and open Documentation/output/index.html in
the browser to see how the added piece looks.

And yes, there's the search box ontop but for the life of me, it is
really hard to find the section which was added from the wild naming and
sorting of the different documentation sections in the left table of
contents. I always have to go map it from the source.

For example:

On the page right it says "Licensing documentation" but that's not in
the left TOC.

Then

"Licensing documentation, ... User-oriented documentation" ... the word
"documentation" is unnecessary. "Linux" in all those section names etc
"is superfluous too.

And then the title format of the sections is kinda different.

And the structure should be probably organized better and not have

"The Linux kernel user’s and administrator’s guide"

on the same level as

"MHI"

for example, whatever that last thing is.

And so on.

So I was thinking that maybe there should be a small set of rules -
don't want to overload submitters :) - about structure and formatting
of each documentation section/file/etc so that the final product can be
more useful and I can actually find something in there. :-)

Thoughts?

Thx.

-- 
Regards/Gruss,
    Boris.

https://people.kernel.org/tglx/notes-about-netiquette