netdev - Re: [PATCH net v2 1/2] docs: networking: convert DIM to 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-prev] [thread-next>] [day] [month] [year] [list]

Date:   Fri, 10 Apr 2020 21:59:56 +0000
From:   Saeed Mahameed <saeedm@...lanox.com>
To:     "kuba@...nel.org" <kuba@...nel.org>
CC:     "jacob.e.keller@...el.com" <jacob.e.keller@...el.com>,
        "leon@...nel.org" <leon@...nel.org>,
        "linux-doc@...r.kernel.org" <linux-doc@...r.kernel.org>,
        "davem@...emloft.net" <davem@...emloft.net>,
        "netdev@...r.kernel.org" <netdev@...r.kernel.org>,
        Tal Gilboa <talgi@...lanox.com>,
        "rdunlap@...radead.org" <rdunlap@...radead.org>
Subject: Re: [PATCH net v2 1/2] docs: networking: convert DIM to RST

On Thu, 2020-04-09 at 16:06 -0700, Jakub Kicinski wrote:
> On Thu, 9 Apr 2020 22:46:55 +0000 Saeed Mahameed wrote:
> > On Thu, 2020-04-09 at 14:21 -0700, Jakub Kicinski wrote:
> > > Convert the Dynamic Interrupt Moderation doc to RST and
> > > use the RST features like syntax highlight, function and
> > > structure documentation, enumerations, table of contents.
> > > 
> > > Signed-off-by: Jakub Kicinski <kuba@...nel.org>
> > > Reviewed-by: Randy Dunlap <rdunlap@...radead.org>
> > > ---
> > > v2:
> > >  - remove the functions/type definition markup
> > >  - change the contents definition (the :local: seem to
> > >    not work too well with kdoc)
> > > ---
> > >  Documentation/networking/index.rst            |  1 +
> > >  .../networking/{net_dim.txt => net_dim.rst}   | 90 +++++++++--
> > > ----
> > > ----
> > >  MAINTAINERS                                   |  1 +
> > >  3 files changed, 45 insertions(+), 47 deletions(-)
> > >  rename Documentation/networking/{net_dim.txt => net_dim.rst}
> > > (79%)
> > > 
> > > diff --git a/Documentation/networking/index.rst
> > > b/Documentation/networking/index.rst
> > > index 50133d9761c9..6538ede29661 100644
> > > --- a/Documentation/networking/index.rst
> > > +++ b/Documentation/networking/index.rst
> > > @@ -22,6 +22,7 @@ Linux Networking Documentation
> > >     z8530book
> > >     msg_zerocopy
> > >     failover
> > > +   net_dim  
> > 
> > net_dim is a performance feature, i would move further down the
> > list
> > where the perf features such as scaling and offloads are .. 
> 
> I mean.. so is msg_zerocopy just above ;-)  I spotted slight
> alphabetical ordering there, which may have not been intentional,
> that's why I put it here. Marking with # things out of order, but 
> based on just the first letter:
> 

Oh i didn't see the alphabetical order :), then i guess your patch is
ok.

> #  netdev-FAQ
>    af_xdp
>    bareudp
>    batman-adv
>    can
>    can_ucan_protocol
>    device_drivers/index
>    dsa/index
>    devlink/index
>    ethtool-netlink
>    ieee802154
>    j1939
>    kapi
> #  z8530book
>    msg_zerocopy
> #  failover
>    net_dim
>    net_failover
>    phy
>    sfp-phylink
> #  alias
> #  bridge
>    snmp_counter
> #  checksum-offloads
>    segmentation-offloads
>    scaling
>    tls
>    tls-offload
> #  nfc
>    6lowpan
> 
> My feeling is that we should start considering splitting kernel-only
> docs and admin-only docs for networking, which I believe is the
> direction Jon and folks want Documentation/ to go. But I wasn't brave
> enough to be the first one. Then we can impose some more structure,
> like putting all "performance" docs in one subdir..?
> 
> WDYT?

That was my initial thought, but it seemed like a lot of work and
really not related to your patch.

But yes, categorizing is the way to go.. alphabetical order doesn't
really make any sense unless you know exactly what you are looking for,
which is never the case :),
For someone who want to learn about performance tuning or something
specific like coalescing, what should they look for ? DIM, NET DIM,
moderation or coalescing ? so if we categorize and keep the subdirs
lists short and focused, it will be very easy for people to browse the
networking docs..

Things can grow large very fast beyond our control.. We should really
embrace the "Magic number 7" approach [1] :)

Helps keep things short, organized and focused.

[1] 
https://www.i-programmer.info/babbages-bag/621-the-magic-number-seven.html

Thanks,
Saeed.