[ovs-dev] [PATCH 0/8] Split up the DPDK how-to
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
+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.
> > 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
> > > 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