[Docs] Adding Missing features to docs

afro-coder commented 2 months ago

Feature request description

Firstly I hope I'm in the correct repository, since there is no Docs template here. Maybe we can add that too.

I'm following this up from the Podman Lists https://lists.podman.io/archives/list/podman@lists.podman.io/thread/CXRQ2QIIWABGJ7BMVW7YTSZFWXAX32R4/

There are certain features which are out in the open but Podman docs has little information on this, I'm appending the things on the thread here.

https://podman.io/docs doesn't mention Quadlet or Pasta anywhere.

https://github.com/containers/podman/blob/main/docs/tutorials/basic_networking.md, the "Network" sidebar link at the above page, doesn't mention Pasta.
https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html is probably the main source of information I used to figure out Quadlet... and it isn't linked to anywhere on docs.podman.io or podman.io/docs that I can see, though it can be found with the former's search function.

Suggest potential solution

I'd like to start a main issue with something like keeping it updated with the features we add or a per issue Pull Request.

I also am running podman on risc-v devices these days and so far it only works correctly with Archlinux and I'd also like to help with that and documenting and testing features on docker and podman.

Have you considered any alternatives?

A clear and concise description of any alternative solutions or features you've considered.

Additional context

Add any other context or screenshots about the feature request here.

cevich commented 2 months ago

Thank you so much @afro-coder for taking the initiative to open this issue and get this effort started! Some logistics tips in case they help:

The podman.io site comes from the podman.io repo. There are some basic items in the docs directory.
The tutorials index on podman.io comes from the podman repo with each page also stored in the podman repo.
Shared documentation (like for containers.conf and the Containerfile man page) come from the containers/common repo.
Beware of podman docs duplication WRT buildah, esp. podman build. The only automation is related to ensuring new buildah features are added into podman docs. Otherwise, keeping the two in agreement is currently a manual effort unfortunately.

afro-coder commented 2 months ago

Ah this is confusing xD but thanks for sharing this, I think I'd start with picking those items testing them and then adding them to the docs whenever I can.

Can we use this as an issue tracker for the smaller issues in different repos?

cevich commented 2 months ago

Ah this is confusing

Precisely why I wrote it :grin:

Can we use this as an issue tracker for the smaller issues in different repos?

I'm not sure how best to organize this effort, but I see no reason why a common issue couldn't be used.

I'll also mention that I've brought this issue and the original ML thread up to the Red Hat team, and it's got traction. The team recognizes this as a sore-spot and has some action-plans in the works. Likely the best way to "tune-in" is by attending the "Community Cabal" meetings and by keeping an eye on the mailing list.

/cc @mheon @TomSweeneyRedHat

TomSweeneyRedHat commented 2 months ago

@Luap99 just running this by you in case you have thoughts on the documentation for pasta and such.

TomSweeneyRedHat commented 2 months ago

@mheon do we have a card, or can we create a card to update the basic_networking tutorial? https://github.com/containers/podman/blob/main/docs/tutorials/basic_networking.md

TomSweeneyRedHat commented 2 months ago

@afro-coder first off, TYVM for this issue. You're pointing out a number of holes that we need to plug.

As @cevich pointed out, the doc page that you pointed to, https://podman.io/docs, lives in this GitHub repo

As you noted, the docs.podman.io site, does have more info on quadlet and pasta both, at least from a man page perspective. I thought we had a link to docs.podman.io on the docs page of the podman.io site. I know we added the "Podman Python Documentation" link on that page not too long ago, I wonder if the docs.podman.io link got wiped during that?

Also, FWIW, the documentation that is seen on docs.podman.io, is driven from this repository.

mheon commented 2 months ago

@TomSweeneyRedHat I think we need to start a spreadsheet listing documentation tasks we want done. Ideally something open to the community so we won't be the only ones contributing to it - and so that the community can easily identify what bits of our documentation really need updating.

cevich commented 2 months ago

start a spreadsheet listing documentation tasks

If it helps, I believe it's possible to make those documents open for public editing? If that's a bad idea, there's also the "discussions" feature. That might work better in terms of involving the greater community.

Luap99 commented 2 months ago

@Luap99 just running this by you in case you have thoughts on the documentation for pasta and such.

It is not really related to pasta, there is a lot of outdated info around networking in general. There are just so many different use case around networking which makes it very hard to document cases users care about. Of course not impossible but if I think about all the cases we support I would think that is at least 10k words to cover all networking basics, gotcha's, etc... And it hard to know what level of experience I can assume. I am certainly not going to explain how ip addresses/networks/routing works.

Fundamentally we are developers and not technical writers and writing good documentation is not a simple task. We can (and IMO should) focus more on that I agree but that depends on how the priorities are set in general.

I like to point out is that most of our man pages are good IMO. Of course you will find some problems here and there. We have automation to ensure all cli options/commands are always documented in its man page. The problems however is that plain man pages are not that useful for most people. Unless you know what you are looking for they will not help. What is more useful are general user guides that explain concepts and use cases and we are missing that in a lot of places or it was not updated (i.e. basic networking guide)

And as pointed out our docs page doesn't even link all man pages we have so many users will not find useful into that exists.

afro-coder commented 2 months ago

Hey folks,

Sorry bit behind on this conversation, I'll read through it again, I'm travelling for the next two weeks but I will try to contribute back with use-cases etc, plus I'm running podman on risc-v devices too and I'd like to contribute back as much as I can.

For beginner stuff we did something similar in terms of explaining networking in the Ingress-Nginx project.

https://github.com/kubernetes/ingress-nginx/blob/main/NEW_CONTRIBUTOR.md

So I guess we can always link it if it's like a beginner thing we need to add. I was thinking we can make a checklist of issues and keep that in this issue itself, easier I guess to manage too(Feel free to correct me I'm not much of a git user)

afro-coder commented 2 months ago

Hey folks, I'm back, I'll start slowly working on this!

Edit: This is taking longer than I expected, I'll get on this soon

containers / podman