[Podman] Re: Help Wanted: Podman Documentation contributors, suggestions, and more....

Hi Tom/Podman Team, I actually wrote a couple of books on Docker and the Ansible Container  project (back when it was a thing). I would love to help with Podman documentation. What is the process for contributing documentation fixes?   Are there specific issues you need pull requests tied to, or could I fix a bunch of issues on a single pull request? Thanks, Aric On Thu, May 20, 2021 at 1:26 PM Erik Bernoth <erik.bernoth(a)gmail.com <mailto:erik.bernoth@gmail.com>> wrote: Hi Tom, 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 [1] 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 [2]: ``` 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 <role> part is called <persona> 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 ``` Best, Erik [1] My training path: https://www.coursera.org/specializations/uva-darden-digital-product-manag... <https://www.coursera.org/specializations/uva-darden-digital-product-manag... [2] https://en.wikipedia.org/wiki/User_story <https://en.wikipedia.org/wiki/User_story> On Fri, 14 May 2021 at 02:15, Tom Sweeney <tom.sweeney(a)redhat.com <mailto:tom.sweeney@redhat.com>> wrote: Recently the community discovered that the Podman Whatis?(https://podman.io/whatis.html <https://podman.io/whatis.html>) 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 (https://github.com/containers/podman/issues <https://github.com/containers/podman/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 (https://github.com/containers/podman/discussions/10336 <https://github.com/containers/podman/discussions/10336>), or send an email to the Podman mailing list (https://lists.podman.io/admin/lists/podman.lists.podman.io/ <https://lists.podman.io/admin/lists/podman.lists.podman.io/>). 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. Best Wishes, Tom Sweeney tsweeney(a)redhat.com <mailto:tsweeney@redhat.com> _______________________________________________ Podman mailing list -- podman(a)lists.podman.io <mailto:podman@lists.podman.io> To unsubscribe send an email to podman-leave(a)lists.podman.io <mailto:podman-leave@lists.podman.io> _______________________________________________ Podman mailing list -- podman(a)lists.podman.io <mailto:podman@lists.podman.io> To unsubscribe send an email to podman-leave(a)lists.podman.io <mailto:podman-leave@lists.podman.io>