Plans for www.podman.io and discussion
All, I've been doing some work on www.podman.io: https://github.com/containers/podman.io/pull/129 This work has some specific goals and assumptions, which I think we should discuss before I put a lot more time into them, and before we also start on a re-templating of the site. Here's my priorities: 1. Make the site more accessible to first-time users 2. Make it easier to contribute to the site itself 3. Look & Feel improvements 2. and 3. are simple and non-controversial; Tuomas and I will go over the site and set up proper Jekyll templating so that anyone in the project can easily add new pages in markdown format. We'll also add some tests for the site (as soon as I get my podman config figured out). 1) is where we need discussion. My thinking is that, at this time, the majority of folks who come to podman.io will be new to PodMan, and as such content aimed at the New User role should be the most prominent in the menus and core pages. The other two roles are "Experienced Kubernetes Admin" and "Contributor", and my plan would be to target improvements for those roles after doing the "New User" role, and actually after tackling the Buildah site as well. One of the corrollaries to this is that I think that all user documentation (as opposed to contributor/developer documentation) should be moved from the Libpod repo to the podman.io repo. My reasons for this are as follows: A. better discoverability; MD pages in github repos have chronically low search ranks, and pages with fixed URLs on Jekyll sites do better. B. reduced confusion; right now users click a link on the "podman" page and get dumped into a github repo called "libpod", where they have to scroll down before they see the docs they're looking for. C. easier acceptance of user doc contributions: they will no longer be libpod PRs, so doc updates can be accepted with less scrutiny, opening the door to getting some doc-only contributors. However, this will mean changing where everyone *maintains* those docs, so we need consensus on it. Comments? -- -- Josh Berkus Kubernetes Community Red Hat OSAS
Hi Josh, thank you very much for sharing your thoughts and for kicking-off a conversation. On Fri, Aug 30, 2019 at 2:35 AM Josh Berkus <jberkus@redhat.com> wrote:
All,
I've been doing some work on www.podman.io:
https://github.com/containers/podman.io/pull/129
This work has some specific goals and assumptions, which I think we should discuss before I put a lot more time into them, and before we also start on a re-templating of the site. Here's my priorities:
1. Make the site more accessible to first-time users 2. Make it easier to contribute to the site itself 3. Look & Feel improvements
2. and 3. are simple and non-controversial; Tuomas and I will go over the site and set up proper Jekyll templating so that anyone in the project can easily add new pages in markdown format. We'll also add some tests for the site (as soon as I get my podman config figured out).
1) is where we need discussion. My thinking is that, at this time, the majority of folks who come to podman.io will be new to PodMan, and as such content aimed at the New User role should be the most prominent in the menus and core pages.
I agree and imagine the site to be very difficult to navigate for new users. It would be great to have some learning material where new users can inform themselves and get introduced to the world of containers.
The other two roles are "Experienced Kubernetes Admin" and "Contributor", and my plan would be to target improvements for those roles after doing the "New User" role, and actually after tackling the Buildah site as well.
One of the corrollaries to this is that I think that all user documentation (as opposed to contributor/developer documentation) should be moved from the Libpod repo to the podman.io repo. My reasons for this are as follows:
A. better discoverability; MD pages in github repos have chronically low search ranks, and pages with fixed URLs on Jekyll sites do better.
B. reduced confusion; right now users click a link on the "podman" page and get dumped into a github repo called "libpod", where they have to scroll down before they see the docs they're looking for.
C. easier acceptance of user doc contributions: they will no longer be libpod PRs, so doc updates can be accepted with less scrutiny, opening the door to getting some doc-only contributors.
However, this will mean changing where everyone *maintains* those docs, so we need consensus on it. Comments?
Having documentation on podman.io would be a great improvement. However, I suggest to keep the docs in the upstream repositories and copy them over to podman.io for new major releases. This way, we can update the docs with the code changes in one PR and don't publish docs of unreleased features. Kind regards, Valentin
Josh, I'm good with all of your thoughts and suggestions. The work that you've done so far has helped a lot. 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? 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. With all that said, I'll favor your experience and judgment on decisions like this. The main goal for the site was to give a place for developers and contributors an easy place to blog to and to be able to get the information out to the end user. Any improvements you can make in getting that info out to the end user works for me as long as the contribution piece still remains easy to accomplish. t
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
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.
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
On 8/30/19 2:21 PM, Tom Sweeney 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
On 08/30/2019 01:44 PM, Josh Berkus wrote: 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@lists.podman.io To unsubscribe send an email to podman-leave@lists.podman.io
participants (4)
-
Daniel Walsh -
Josh Berkus -
Tom Sweeney -
Valentin Rothberg