[feature request] Integration with Open vSwitch docs

[stephenfin]

This could be a controversial idea 😄

With the latest release of Open vSwitch, the entirety of the in-tree documentation has been moved to reStructuredText and Sphinx and published online. I did most of this work and structured the docs very similarly to the Django project (which has the best documentation I've found to date), meaning there are a variety of installation guides, some howtos and tutorials, some deep-dive overviews of the code itself, along with a couple of other sections.

Having scanned through the material you've written thus far, it would appear there's going to be a high degree of crossover between these in-tree docs and the ovs-cookbook project, leading to my question: would it be possible to get this material published as part of the in-tree Open vSwitch docs instead and, if not, is there anything we could do to make this possible?

[scottslowe]

@stephenfin Great work on the docs! While there does appear to be a fair amount of cross-over, I think that the content here is going to be:

• less formal than the in-tree docs;
• more varied than perhaps the in-tree docs (meaning we'll have some recipes here that are likely to be to too esoteric to include in the in-tree docs; and
• have a lower barrier to entry than the in-tree docs (Markdown is easier than RST and contributing here is likely to be easier than contributing to the main OVS repo).

This effort may also serve as a decent "proving ground" for recipes that may later graduate to the in-tree docs based on popularity, quality, etc. I could certainly see stuff the community finds useful moving from here into the in-tree docs over time, if so desired.

Thoughts?

[stephenfin]

@stephenfin Great work on the docs! While there does appear to be a fair amount of cross-over, I think that the content here is going to be:

less formal than the in-tree docs;
more varied than perhaps the in-tree docs (meaning we'll have some recipes here that are likely to be to too esoteric to include in the in-tree docs; and
have a lower barrier to entry than the in-tree docs (Markdown is easier than RST and contributing here is likely to be easier than contributing to the main OVS repo).

I guess each of these could be solved if we wanted. Not only is the definition of what's valuable or "formal" enough for in-tree docs entirely arbitrary (and therefore debatable 😃), I'm sure we could do something to make contributing docs to OVS somewhat easier (ideas on this below). The only one that would be awkward would be Markdown vs. rST - OVS used to use the former and it caused a lot of issues due to lack of features like validation and cross-referencing. Converting it to rST was an arduous task but it provided enough useful features to make it ultimately worth it. I'd say we could work around this somehow?

This effort may also serve as a decent "proving ground" for recipes that may later graduate to the in-tree docs based on popularity, quality, etc. I could certainly see stuff the community finds useful moving from here into the in-tree docs over time, if so desired.

So this is the main thing I'm trying to avoid, heh. IMO, it would be awesome if we get everything in the one, "blessed" location and avoid both the duplication and the copy-convert-paste cycle to add things to the upstream docs, and it would also be amazing to get another editor (rather than a developer - they're totally different skillsets) working on the upstream docs. There are certainly some things that don't belong in upstream docs, but, assuming you plan to vet contributions, I imagine those same things wouldn't belong here either?

Thoughts?

I'm not at all suggesting you don't pursue this project and think all Open vSwitch users, including you and I, would benefit from whatever you do choose to do. Rather, I'm suggesting that there are many benefits to having everything in one location and maybe we could work with the Open vSwitch maintainers to minimize any barriers to entry before tacking another course. Totally up to you 😃

---

Ideas for making contributions easier:

• Move docs to a separate repo
• Ask maintainers to fast path doc-only changes (or look for additional, doc-only sub-maintainers a la the kernel)
• Provide a WYSIWYG editor for people to submit docs without worrying about Git, etc. (a wiki?)
• Write a bot that converts any changes to this project into patches for https://github.com/openvswitch/ovs/ (my least favorite, heh - too much duplication)

[stephenfin]

Per IRC discussion:

<sfinucan> russellb: Would appreciate your input on #4
<sfinucan> It's totally up to Scott, of course, but I'd like to see if you think minimizing barriers to entry is something the OVS community could do/would care for?
<sfinucan> I'd ask Ben and Joe too, but I don't know their IRC nicks 🙈
<switchcade> sfinucan: I think you're looking for blp and me - although it doesn't look like Ben's in IRC right now.
<switchcade> typically sending an email to us (and/or on the list) is a good way to put an item in our todo list to follow up
<switchcade> it'd have to be something to discuss on the ovs-dev list, but I could plausibly see a situation where there is a docs-only maintainer who manages changes to Documentation/ through the github interface
<switchcade> I like that the docs come with the code, this means we can keep both up to date (so long as we're looking out for keeping them up to date), and also if someone just gets a source tarball or git from somewhere, they don't have to rely on fancy websites to get their documentation

[scottslowe]

@stephenfin After careful consideration, I've decided to shut down this project and instead focus on the upstream docs. Given the extensive changes in the docs, I think it's now reasonable to go down this path instead of creating yet another source of documentation. Thanks for the guidance!

[stephenfin]

@lowescott Good stuff. If I can do anything to help you with that, feel free to ping me on IRC (sfinucan) or via email. Feel free to Cc: me in any patches you'd like to me to take a look at too