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