Valentin, Tom:
My main concern is the same as Valentin's. The location of the
documents. I understand your point about the HTML being hit more than MD files and
it's easier to find. However, would having upstream doc on the site be confusing to a
new end-user?
Why would it be confusing? Where would they be expecting to find it?
The canonical documentation for kubernetes is on kubernetes.io. In
fact, that's 95% of the site.
Transferring the pages as Valentin suggests with each release would
be doable, but painful. Who knows, maybe the user would be using upstream code anyway and
would need the latest/greatest docs. A bit of a six of one, half dozen of another
situation.
See, this is why I wanted to have a discussion about it.
Some arguments against that approach:
1. No new user of podman will be expecting to find docs in a repository
called "libpod". Really, not ever.
2. The "we need docs in libpod so that we can have latest-version
development docs" would be a stronger argument if the docs in libpod
repo were, in fact, being kept up to date with the most recent changes;
I've used that workflow before so it was one of the things I looked for.
However, having been through the installation, usage, and rootless docs
recently for my own use, those aren't even completely current with
Fedora packaged versions. It's possible that other documents are more
current.
3. The final argument against this approach is that one of the things we
discussed on our call was how you needed help at release time to publish
the release notes and other artifacts; this would be adding another,
time-consuming, task to the release process.
Counter-Argument: copying over the docs just isn't that hard, though
tedious, and in fact could probably be fully automated if folks are
willing to make some small changes in how the docs are written in the
libpod repo (mainly, inserting headers and using absolute links).
Counter-Counter-Argument: having the canonical docs for many, but not
all, pages in libpod/ pretty much eliminates the possibility of
recruiting docs-only contributors. It will be too confusing/frustrating
to contribute to the docs if you're not full-time on the project.
Question: *why* is there a large delta between the dev and release
versions? Should podman be releasing more often?
--
--
Josh Berkus
Kubernetes Community
Red Hat OSAS