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. 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 > > d...@openvswitch.org > > https://mail.openvswitch.org/mailman/listinfo/ovs-dev _______________________________________________ dev mailing list d...@openvswitch.org https://mail.openvswitch.org/mailman/listinfo/ovs-dev
