thank you very much for sharing your thoughts and for kicking-off a conversation.
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