[ovs-discuss] Centralizing OVS-DPDK Blogs

Stephen Finucane stephen at that.guru
Thu Mar 30 10:34:53 UTC 2017


On Thu, 2017-03-30 at 09:18 +0000, Stokes, Ian wrote:
> > > On Mar 28, 2017, at 4:15 AM, Stokes, Ian <ian.stokes at intel.com>
> > > wrote:
> > > 
> > > Hi All,
> > > 
> > > There are a number of useful blogs maintained by Intel for OVS-
> > > DPDK. These range from simple 'how-to' articles for specific
> > > feature more technical deep dives of how features work under the
> > > hood.
> > > 
> > > Currently these blogs are hosted on the Intel Developer Zone (and
> > > will continue to be), but there have been suggestions that it
> > > could be useful to expose them in a more central manner to OVS
> > > users.
> > > 
> > > This could include one or more of the following
> > > 
> > > 1. Expand existing OVS docs with blog content.
> > > 2. Adding the blogs to the OVS cookbook.
> > > 3. Creating a news feed for OVS using something like the Planet
> > > feed reader for the OVS webpage. (http://www.planetplanet.org/)
> > > 
> > > This issue was raised at the OVS-DPDK community meeting and it
> > > was decided to kick off a community discussion for more input
> > > before taking action.
> > > 
> > > Do people feel centralizing OVS-DPDK content to the OVS project
> > > would be useful or is the status quo preferred?
> > 
> > Thanks for bringing this up.  For basic documentation, I think it
> > makes sense to expand the existing docs where appropriate.

A similar discussion came up recently w.r.t. Scott Lowe's ovs-cookbook
project [1]. The general point I made was that there were immense
benefits to having a central, "blessed" location that one could use as
a reference guide for all things OVS. Scott seems to have agreed with
this and has stated that he will look to the upstream docs instead [2].

I bring this up because what Scott was working on to date in the book
[3] was, IMO, the kind of documentation that we want in the upstream
docs. These can be seen in the 'How the Documentation is Organised'
section on the front page of the docs and I'll reiterate them here:

- Installation guides for various platforms, *remembering that the vast
majority of users don't need to build from source*.

- Overviews of the various features OVS supports. These should include
brief (read: make assumptions about the environment) configuration
steps for same.

In addition, the following wouldn't have been covered by his work but
are currently included in the docs and are worth expanding where
possible:

- A handful of highly detailed tutorials that show users how to build
OVS/OVN deployments of varying complexity from scratch. These should be
reproducible by users with only a moderate investment of resources and
time and make far less assumptions than the HOWTOs.

- Reference guides for the various tools that OVS provides
(generally man pages), along with any public APIs it might offer
(Doxygen-style)

- FAQs that don't really fit into any other sections

On the other hand, there are things that don't really make sense in the
upstream docs and that I would not like to see included:

- Esoteric or very advanced use cases of OVS. Detailing how you wired
up your entire data centre using a single instance of OVS would make
for an amazing (and implausible) blog post, but it's unlikely to be
useful to the majority of users.

- Usage of OVS in other projects, e.g. OpenStack Neutron. Those other
projects should contain this documentation - not OVS.

- Detailed benchmarking and/or debugging information, or other items
that would not be useful to the majority of users.

Having looked through the links you provided, Ian, most of these blogs
would make sense in as docs and would be worth adding there. If you
were to include them, I'd be happy to review (Cc: me) and I think it
would OK to include a note at the top stating the original source of
the material contained within. There are some that don't (my own
OpenStack'y blog post, the VTune one and possibly the NUMA support
overview, to pick a few) and these can be excluded.

> > We've talked about adding some cookbook-like documentation for
> > OVN.  It would be nice to use the same mechanism for both.  In the
> > past, we've hosted cookbooks on the main OVS website, but they
> > weren't regularly updated, and sort of fell into disrepair.  A good
> > path forward might be to introduce them into the OVS repo, since
> > they're now displayed nicely through Read the Docs
> > (https://readthedocs.org).

The OVS docs are already in the OVS repo and have been removed from the
site [4].

> +1 on this, using the repo is a good way to future proof the material
> which is also a goal of centralizing them.

You also get version control, so if a command in some HOWTO or tutorial
changes in the future and you want the version that works with older
packages, they can be easily retrieved.
 
> > I'd be curious to get others' opinions--especially Ben and Stephen
> > since they were so involved in the last documentation overhaul.
> 
> Good idea, any input would be appreciated.

I'm also totally onboard with the idea of listing things from around
the blogosphere on the openvswitch.org website. I've been thinking
about reworking that site to use Sphinx too (instead of Jekyll) to
allow us to share resource, such as themes, with the docs project. If
we took this route, a variety of Sphinx extensions exist that would
make this very easy to do. This is probably a discussion in its own
right though.

Hope this helps,
Stephen

PS: I've highlighted this before, but my thoughts on things
documentation are heavily influenced by the work done by the Django
project. IMO, theirs is the best documentation in the business, hands
down. Well worth a look.

[1] https://github.com/lowescott/ovs-cookbook/issues/4
[2] http://blog.scottlowe.org//2017/03/28/canceling-ovs-cookbook-projec
t/
[3] https://github.com/lowescott/ovs-cookbook/blob/master/summary.md
[4] http://docs.openvswitch.org/en/latest/howto/


More information about the discuss mailing list