4:51 a.m.
On 8/30/19 2:21 PM, Tom Sweeney wrote:
On 08/30/2019 01:44 PM, Josh Berkus wrote:
> 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?
I don't think it would be confusing as far as the physical location of
the document. The confusion point I could see is this scenario:
New User does 'dnf -y install podman`
`podman pull --new-upstream-only-option my-image` that they find on the
doc.
and then they get an error that `--new-upstream-only-option` doesn't
exist. It's a version skew issue that I think might cause issues from
time to time that I'm a little concerned about.
Well we are always going to
have this, since people are going to be
running ancient versions of podman on RHEL and Centos for example.
> 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?
>
I'm not sure that there's a large delta between dev and release, but
could be convinced otherwise. More frequent releases would certainly
help this problem get even smaller and I'm all for it. We've had
ongoing discussions on what a good release cadence should or should not
be, but I don't think we've settled on anything at this point.
t
_______________________________________________
Podman mailing list -- podman(a)lists.podman.io
To unsubscribe send an email to podman-leave(a)lists.podman.io