Documentation/index.rst

Documentation/index.rst

[Borislav Petkov]

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

Re: Documentation/index.rst

[Jonathan Corbet]

Borislav Petkov <bp@alien8.de> writes:

> 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. :-)

Totally agreed.

When I took on Documentation/, it was one big pile of random stuff.
Since then, I've been pushing to organize things into various "books"
with some success, so that now we have several smaller piles of random
stuff.  I do think it's an improvement, but the job is far from done.

$SOMEBODY really needs to do a pass over the top-level index.rst and
create some better order there, it's been a while.  I'll try to get to
that soon (if nobody beats me to it - a likely outcome :), but it won't
be right away.

thanks,

jon