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

Stokes, Ian ian.stokes at intel.com
Tue Apr 17 18:38:26 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.

Sure and I agree, what we have now is more maintainable, I don’t support reverting to the old approach, just pointing out one of the advantages it had that the community felt was lost. I don’t think there's anything inherently wrong with the current approach but there is a disconnect somewhere we need to address.

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

Do we call this out clearly to users somewhere?

It's clear when writing/reviewing a patch series like this that the docs adhere to this model (and makes sense) but this might not be the case for a new user.

We could call it out in the top level readme.rst. It already has a documentation availability section, it could be expanded with a section explaining where users should start with the docs. TBH it would help when new features are added also as we can point to what's expected.

> 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 in the v1 review set we're already starting to add cross referencing to help address this so it negates the need for a document map. I'm also happy to see the changes such as the version change tags coming in.

From the reviewing/maintaining side it's always easier to point to these type of examples so that they can be followed in future docs.

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

+1 on this, I wouldn't limit it to just Intel and Red Hat either. IMO addressing documentation issues is a community wide effort, all are welcome to provide input on this work to address issues they have experienced. Specific examples will help here so I would encourage users to participate :).

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

Sure, and thanks for working on the series, appreciate the effort, should have time to review the v2 tomorrow. 

Ian

> 
> Stephen
> 
> > 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