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@xxxxxxxxxx>
> > > > Reviewed-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
> > > > ---
> > > > 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
