All,

    I chatted with Mehul today and I want to start a conversation around how we could improve the docs. Here are my thoughts:

1. Figure out a way to keep the main page canonical sources on https://github.com/containers/podman/tree/main/docs/source/markdown
2. Synchronize https://github.com/containers/podman/docs/source/markdown to github.com/containers/podman.io/docs/source/markdown
3. Let's move everything else from github.com/containers/podman/docs over to the github.com/containers/podman.io/docs
4. Update the theme to this new theme Mehul tested [1] call furo. Feel free to test that container image. It pulls the content from the current repository.
5. If we do #3, we can make it easier for people to commit docs because it wouldn't need to go through the full CI/CD gating tests (might not be correct. Is the podman.io repository gated by the same CI/CD?)
6. Second, we could have dedicated editors instead of engineers approve docs changes

An alternative to this proposal could be to use a completely new repository apart from podman.io. If we can separate the docs out, I think we could find volunteers to be editors (aka approve PRs). This would allow core code contributors to focus on code, and docs volunteers to focus on docs. Stated another way, I don't think docs needs CI/CD like code. I think editors probably do a better job (though CI/CD could be useful for link checking, etc).

Thoughts?

[1]: 

FROM fedora:latest

EXPOSE 8000
RUN dnf install -y gpgme-devel \
		libseccomp-devel.x86_64 \
		systemd-devel \
		make \
		git \
		golang \
		python \
		&& export PKG_CONFIG_PATH="/usr/lib/pkgconfig"


RUN cd / && git clone https://github.com/containers/podman.git \
	&& cd podman \
	&& make install.tools

RUN cd /podman/docs \
	&& dnf -y install python3-sphinx python3-recommonmark \
	&& pip install sphinx-markdown-tables furo \
	&& sed -i 's|html_theme = "alabaster"|html_theme = "furo"|g' /podman/docs/source/conf.py \
	&& make html

WORKDIR /podman/docs

CMD ["python", "-m", "http.server", "8000", "--directory", "build/html"]

Best Regards

Scott M

--

--

18 ways to differentiate open source products from upstream suppliers: https://opensource.com/article/21/2/differentiating-products-upstream-suppliers 
--

Scott McCarty
Product Management - Containers, Red Hat Enterprise Linux & OpenShift
Email: smccarty@redhat.com
Phone: 312-660-3535
Cell: 330-807-1043
Web: http://crunchtools.com

_______________________________________________
Podman mailing list -- podman@lists.podman.io
To unsubscribe send an email to podman-leave@lists.podman.io