On 2016-10-05 17:29, Ben Pfaff wrote:
On Wed, Oct 05, 2016 at 10:05:50AM +0000, Stephen Finucane wrote:
[snip]
3) Rework docs into a series of guides
I see the following guides as being helpful
- Installation guide
- Usage guide
- Contributor guide
I had a 'testing-guide', but this makes more sense split between
the
middle two. Any other guides?
We probably want to have separate guides for OVS and for OVN, at least
for installation and usage.
Agreed. I'll scope this out a little further once the basic conversion
is complete.
This would be three separate series so I don't have to do everything
at
once. I'd also welcome assistance from anyone who wants to take the
chance
to rework some aspect of the docs.
I can help with some MD->RST. You mentioned that you've already done
it
for about half the docs and hadn't posted all of those.
I've actually got a good deal more done over the weekend (it didn't stop
raining) so there's only the below left:
- INSTALL.Fedora.md
- INSTALL.Libvirt.md
- INSTALL.RHEL.md
- INSTALL.SELinux.md
- INSTALL.SSL.md
- tutorial/Tutorial.md
- tutorial/OVN-Tutorial.md
- ovn/CONTAINERS.OpenStack.md
- ovn/OVN-GW-HA.md
- Documentation/OVSDB-replication.md
- Documentation/release-process.md
(I'm also half way through the FAQ, which is crazy long and should
probable be broken up at some point)
I won't get a chance to work on these until next weekend at the
earliest, so if you (or anyone) wants to take a look at any of that
would be helpful.
As far as converting goes, I've found a lot of the Markdown is broken
meaning pandoc doesn't handle it well. Doing it manually takes as much
time as fixing the badly parsed text and gives you the chance to
refactor some stuff.
Thanks a lot for taking this on! It's something I've thought of before
(I was thinking of a DocBook or Texinfo route, although I wasn't really
satisfied with either of those; Sphinx seems fine), but I've never
actually taken it on.
No problem. reST is definitely the best choice based on my
investigations and ties in well with related projects. Hopefully this
helps lower the entry curve for OVS yet more.
Stephen
_______________________________________________
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev
