Help Wanted: Documentation contributors, suggestions, and more

[TomSweeneyRedHat]

Recently the community discovered that the Podman Whatis? page had badly lagged behind the reality of Podman. For example, the page talked about the soon-to-be-released REST API (released a few months ago), and other upcoming features that were already in play. Additionally, over the past few months, inquiries have been made over the availability of several documents: specific "how-to's", a user guide, rootless container tutorials, networking tutorials, and a few issues have been lodged against various parts of the existing documentation.

The maintainers of Podman have recognized that the documentation for the project is not at the level it should be, even though we have made our best effort to do so. At this point, we are hoping to get help from the community. The level of help that we would like to get is varied. At the top of the list would be creating issues for any missing or incorrect documentation. If someone in the community likes going through man pages and making sure they're formatted consistently, we'd love their help. If you ever wanted a big documentation project that you could stamp your name on, then the Podman Users Guide might be a great way to increase your documentation chops. Any help that you would be willing to offer to better Podman's documentation would be gratefully accepted.

Also, if you or someone you know is not terribly technical yet wants to contribute to an Open Source project, this might be a great opportunity to get your foot in the door. We'd be more than happy to walk someone through the git submission processes in exchange for documentation improvements for the project. Or if they're more comfortable sending in something via email, we'd be happy to deal with the git side of things.

So if you have documentation improvement ideas or suggestions, please add a comment to the discussion here, or send an email to the Podman mailing list. Paraphrasing Richard Branson: No idea is too small, and all sorts of ideas have the potential to change the project as we know it for the better.

We have an absolutely terrific and growing Podman community. Hopefully, this effort will garner more contributors and create better documentation for Podman. Thanks for your attention, and feel free to contact me if you have any questions.

Tom Sweeney
[email protected]

[Procyhon]

I have noticed that the man pages are not consistent from the formatting point of view. I would like to propose a standard formatting and then adapt all the man pages that need it.

[rhatdan]

SGTM, note all man pages are generated by Markdown.

[TomSweeneyRedHat]

@Procyhon IDK if you're up for making the changes, but any suggestions of particular areas of concern that you could point out would be helpful too.

[Procyhon]

The man pages follow the same general structure. One example are the options. When one refers to an option in a description text sometimes it is written in bold sometimes in italic and sometimes highlighted with backticks. Another thing is, that some options require arguments but are not shown with an equal sign while others are. The man pages should have the same formatting to ensure user friendliness.

[erikbgithub]

Copying over from email:

This request really speaks to me. Sadly, I'm super busy these days with different kinds of training. But I found a way to connect the homework in my Coursera Product Management certification course with your interest for more tasks. I'm curious if you or others think this might be helpful. For instance, maybe someone already feels that is a good representation of their situation, or they know someone like that, or some of my assumptions are totally wrong because... etc.

Context:
I believe that all activities in regards to documentation, training and customer acquisition should have a primary focus on the users and their actual stories. So before writing suggestions for how to improve the documentation, I would first like to know some Podman power users (or Docker power users, or virsh power users), what they do with the provided tooling, how their activities connect to each other, why they are doing things one way or another, and which problems they are facing while doing so.

At the same time my product management training also discusses how product managers should understand and approach users. The main work item for product managers is the User Story. That is an Issue, Bugzilla, or Jira ticket where the description is formatted in a certain way:

As a <role> I can <capability>, so that <receive benefit>

To be able to write stories, first I have to understand about whom I write them.

The part is called in our training. That means, a representative example of a certain group of users. And we learn to understand them by making assumptions about what they Think, Feel, See and Do, and then we go out and test these assumptions by actually talking to people who fit this profile.

As one homework we should brainstorm, how users for a scenario of our choice would look like, and I chose "distributed container workloads too small for Openshift". The following is my homework response:

Brainstorming Personas for distributed container workloads too small for Openshift installations:
 - Jon the smarthome maker. He likes to tinker around in his house. He also likes to use open source. It's a tat more work to set up. But he doesn't mind. He likes that he can understand some of the parts that go into his system, though. And he likes that usually these components come with a community of dedicated hobbyists and professionals, just like himself.
 - Sven the racing simulator builder. Sven loves cars. Sven loves racing. But not in the real world, where gas is expensive and you could actually get hurt. He prefers simulators. And he knows there are a lot of simulator fans out there, willing to spend a premium for a real-world feeling. So he buys car parts from his trusted scrapyard connections, cuts off the parts that won't fit into a living room, then replaces the dashboard components with raspberry pis, puts movable arms with motors around the driver's seat, and then connects everything to gaming PCs. As a last step he takes his library of actuator controllers and sensor analysing software and rolls them out to the seat controller, dashboard components, and connects them to the gaming PC/hub. Once he's done and played around with it for some time he gets bored. So he sells it in the racing simulator community and starts his next simulator.
 - Tom, the factory maintenance team lead. He found through coincidence on Youtube one day that most of the machines in his factory actually are able to be configured and analysed via normal ethernet ports, USB, and CAN bus (the last one is probably technically wrong, but there will be something similar). So he got this idea that instead of having one of his guys walking through the whole hall once every hour and still missing the red, blinking light on Machine3 before it crashes, he puts Raspberry Pis next to all his machines, figures out how to connect them to the machines, how to read out the data streams, and send them to his office desk PC in the supervisor office from 2005. There he uses Prometheus to analyse when certain limits in the machine's data are reached, and then he can send someone to a machine that specifically needs maintenance.
 
 Persona of Jon the Smarthome Maker:
 Jon thinks:
  - Using technology to solve his daily problems is good.
  - Having insight into how this software is used and build is good.
  - Building software from independent components is good.
  - Interacting with a healthy community around these components is good.
 Jon sees:
  - Many companies in the hardware store advertise their product's smart capabilities.
  - Many companies offer iphone and windows apps to manage their devices.
  - Almost no company offers to manage other company's devices as well.
  - Almost no company can explain how the data is exchanged, stored, and kept safe from external influences through the management apps.
  - Many products offer some form of open standard to connect to.
 Jon feels:
  - He shouldn't buy an iPhone to change is bathroom light from green to pink.
  - He feels overwhelmed with the amount of individual, proprietary solutions to part of his smart home dream.
  - He feels disappointed that many smart devices only add features to traditional parts of his house which he doesn't really need.
  - He feels disappointed that many smart devices don't consider how he wants to use them together (e.g. light, heating, A/C and roller blinds).
  - He feels sad that he can't share this hobby with his brother, who's a lawyer with no technical background, due to lack of standardization and automation
 Jon Does:
  - Buys smart devices that have open standards and can be connected to open source hubs.
  - builds small hubs with raspberry pis that collect all the data from one part of the home.
  - builds a central hub in the garage, at first with a raspi, and thinks about upgrading it to a NUC later.
  - manually rolls out the software stacks on linux with docker, because that is what the youtube videos recommended him to do
  - configures the network connections manually
  - has no plan for upgrades
  - ignores firewall and security upgrade related planning
  - if a sensor, actuator, room-hub or the central hub die, he will manually rebuild a new one and just accept the outage in usability and data collection
  - ignores backup considerations
  - when running into an issue during deployment he reaches out to the component's community via mailing list or slack channel
  - in one python component a configuration value was not accepted in the form described in the documentation, therefore he sent a patch
  - in another project the usb driver was not able to read the sensor data from the cable; after trying to get an *alternative* project to work he gave up without reporting the problem to anybody
  - in the community where he provided a patch the other members got really excited and asked him to present his setup in their monthly call; he really wants to, but can't find the time prepare some powerpoint slides

[rhatdan]

Most of the questions we face are around rootless containers.

How do I configure rootless networking? Bind to ports < 1024 in rootless. Communicate between containers/pods in rootless mode...

Also we get lots of people asking about running podman/buildah within containers launched by different container engines. Podman In Podman, In Docker, In Kubernetes/OpenShift.

Podman on MAC?

Rootless Podman handling volumes. SELinux, User Namespace, Supplemental group access.

We have written lots of Blogs on this stuff over the years, but they are not organized, and are spread around.

I do question how users find this type of data now, Would they go through a podman.io or github.com/containers/podman web site to look, or do they just google it. (This is what I do)

[SamYuan1990]

Hi guys,

here is my point of view:

1. I hope that podman document able to as much details as docker with key points related with development. for ex https://docs.docker.com/network/ and https://docs.docker.com/storage/, as you may know when we use any kind of container technology tools. we'd better to have some pages with technology details as wiki, or knowledge base.
2. I hope that we considering with i18n support for other language for ex Chinese.

here is my questions:

• is there any planned issue/meetings there?
• any label for document related issue?
• how to contribute to the document works?

Thanks and Regards
Sam

[SamYuan1990]

@TomSweeneyRedHat please let me know your feedback with my comments above. thanks.

[TomSweeneyRedHat]

@SamYuan1990 thanks for the note.

1. is there any planned issue/meetings there?
   There are a couple of documentation issues on the board now, but they are not related to the network, storage, or for that matter a user's guide. We recently had a student group led by @rvandernoort start looking into building a "New to Podman" user guide which I think is fantastic. We do have everything covered in man pages but haven't yet found people to write a full guide. Hopefully, that will change as you are right about their usefulness. I'm very open to having some issues spun up pertaining to documentation though.

2. any label for document related issue?

Currently just one, "Documentation".

3. how to contribute to the document works?

We're very open to ideas and suggestions in this arena. Most of the maintainers are coders, not folks that like to create documentation. They're happy to do a man page, but they are not up for doing a full-blown guide. There is a rumor about a certain high-level maintainer might be writing a book, but that won't be ready for a few more months.

Otherwise, I'd like to see that anything that is written is submitted to the GitHub repository for Podman, and then put under the docs directory so that it would then be added automatically to docs.podman.io. However, I'm sure there would be some adjustments needed in the logic that does that publishing to get a new guide type of document out there. I doubt insurmountable.

As far as I18N goes, we've had a few people volunteer to convert man pages, some blogs, and other docs into Japanese, Mandarin, and I think another language. We're very open to that, but not a skill set that many, if any, of the maintainers have.

Holler if I didn't answer any of your questions, it's late where I'm at, and my eyelids are winning the war!

[TomSweeneyRedHat]

And I realized I forgot to answer the meeting question. We've had a few talks at the monthly Cabal meetings which happen on the third Thursday of the month. Which reminds me, I'm very late getting the notes from the last one up on the site.

[SamYuan1990]

thanks, I will try to access the meeting. but as I live in Beijing, China. I am not sure if I am able to access Cabal.
But anyway, I will take a look and have a try.

Thanks Tom.