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

Message-ID: <20200410182520.34157620@kicinski-fedora-pc1c0hjn.dhcp.thefacebook.com>
Date:   Fri, 10 Apr 2020 18:25:20 -0700
From:   Jakub Kicinski <kuba@...nel.org>
To:     Saeed Mahameed <saeedm@...lanox.com>
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 Fri, 10 Apr 2020 21:59:56 +0000 Saeed Mahameed wrote:
> 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.

Cool, applied.

> > #  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..

Fully agree.

> 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

Here I thought the magic number was 3 :-P

https://queue.acm.org/detail.cfm?id=3387947