[ovs-dev] [PATCH 0/8] Split up the DPDK how-to

Stephen Finucane stephen at that.guru
Tue Apr 17 13:04:38 UTC 2018

On Mon, 2018-04-09 at 15:15 +0000, Stokes, Ian wrote:
> > The DPDK howto has slowly morphed into a catch all for everything DPDK,
> > which goes against the original design goal for 'howto' documents [*].
> > This series attempts to return some sanity to the universe by splitting
> > this document into many more 'topic' documents. Along the way, we add a
> > lot of semantic markup, rework some text, and add an overview on 'dpdk'-
> > type ports (the original goal here).
> Thanks for working on this Stephen.
> I'm in favor of improving the documentation but we need to be careful
> when splitting it further apart. I think we should do this only where
> it makes sense.
> Since moving to the current documentation design layout a common
> complaint I've heard at the community call is that users don't know
> where to find specific info as there are multiple locations dealing
> with the same topic. It can be argued that this info exists in
> different locations due to the differences in the type of content
> expected i.e. the difference between what is put in an intro, how-to
> or tutorial. But this can be non-obvious to a user. It seems the
> technical details of these differences are hampering the ease of use
> from a user POV.
> I'd agree the previous approach of having a single DPDK doc catch all
> is far from ideal but one aspect users liked was that it was a single
> clear location.

I both understand and agree with all the above: there's definitely room
for improvement here and it's quite likely that we've made things less
discoverable in how we approached this. That said, I'd be very wary of
any kind of knee jerk reaction, whereby we go from one extreme to
another. As anyone who's ever worked with internal wikis on crufty
codebases will realise, things become increasingly difficult to
understand and maintain when you stop enforcing strict organization
around where things should go. That's not something I want to embrace.

The original intention of splitting this stuff up was so that we could
focus on different kinds of users:

- tutorials: beginners wishing to get started with OVS
- howtos: more experience users wishing to attain a given configuration
- topics: advanced users wishing to deep dive on certain areas

Something like a document map would help, however, I think a better
plan would be to ensure we provide mechanisms to guide people from one
section to another. This could be achieved by adding additional cross-
references (For more information on this topic, refer to XYZ) along
with 'Further Reading' sections at the bottom of the document. I've
touched on this in v2 of this series.

I think the best thing you could do here is get specific examples of
where the docs fall down via proper usability testing. I've heard lots
of complaints about various aspects of the docs but have never
collected these to build up a clear picture (with the exception of the
tunnelling documentation, which has come up more times than I can
count). My work on OVS occurs almost entirely off the clock so this is
not something I would be able to tackle. However, I have asked about
this internally and will continue to do so. In addition, I do think
this may be something Intel could invest some of their considerable
resources in addressing, perhaps instead of writing yet more OVS blogs
(something Red Hat is also guilty of).

In any case, I am happy to help out here and would like to see the docs
be the best docs they can be (TM). I do think this series is a good one
that adds lots of useful information and I also think it's something we
can build upon going forward. Be sure to let me know if you have ideas
on the off chance that I could help you drive them forward.


> Possibly a document map at a high level could help with this.
> I be interested for others input on this series as well.
> Thanks
> Ian
> > 
> > There's a good chance I've made some mistakes in the process and I've left
> > TODOs for someone to resolve now or at a future date. I welcome feedback
> > on both of these.
> > 
> > Now to go back to figure how exactly NUMA affinity works for and affects
> > PMD threads...
> > 
> > [*] 'howto' documents are supposed to be brief, high-level overviews on
> >     a particular group of features, with a focus on the user. They're
> >     not as all-encompassing as a 'tutorial', but not as specific as a
> >     'topic'.
> > 
> > Stephen Finucane (8):
> >   doc: Add an overview of the 'dpdk' port
> >   doc: Add "PMD" topic document
> >   doc: Move additional sections to "physical ports" doc
> >   doc: Move "QoS" guide to its own document
> >   doc: Add "bridge" topic document
> >   doc: Move "pdump" guide to its own document
> >   doc: Split Jumbo Frames guide between two docs
> >   doc: Final cleanup of the DPDK howto
> > 
> >  Documentation/conf.py                    |   2 +-
> >  Documentation/howto/dpdk.rst             | 453 +++-----------------------
> > -----
> >  Documentation/topics/dpdk/bridge.rst     | 103 +++++++
> >  Documentation/topics/dpdk/index.rst      |  11 +
> >  Documentation/topics/dpdk/pdump.rst      |  65 +++++
> >  Documentation/topics/dpdk/phy.rst        | 242 +++++++++++++++++
> >  Documentation/topics/dpdk/pmd.rst        | 139 ++++++++++
> >  Documentation/topics/dpdk/qos.rst        | 100 +++++++
> >  Documentation/topics/dpdk/vhost-user.rst |  53 +++-
> >  9 files changed, 740 insertions(+), 428 deletions(-)  create mode 100644
> > Documentation/topics/dpdk/bridge.rst
> >  create mode 100644 Documentation/topics/dpdk/pdump.rst
> >  create mode 100644 Documentation/topics/dpdk/phy.rst  create mode 100644
> > Documentation/topics/dpdk/pmd.rst  create mode 100644
> > Documentation/topics/dpdk/qos.rst
> > 
> > --
> > 2.14.3
> > 
> > _______________________________________________
> > dev mailing list
> > dev at openvswitch.org
> > https://mail.openvswitch.org/mailman/listinfo/ovs-dev

More information about the dev mailing list