8:13 p.m.
Recently the community discovered that the Podman
Whatis?(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) 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), or send an
email to the Podman mailing list
(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
1:24 p.m.
New subject: Help Wanted: Podman Documentation contributors, suggestions, and more....
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...
[2] https://en.wikipedia.org/wiki/User_story
On Fri, 14 May 2021 at 02:15, Tom Sweeney <tom.sweeney(a)redhat.com> wrote:
Recently the community discovered that the Podman
Whatis?(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) 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), or send an
email to the Podman mailing list
(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
_______________________________________________
Podman mailing list -- podman(a)lists.podman.io
To unsubscribe send an email to podman-leave(a)lists.podman.io
3:39 p.m.
New subject: 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> 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...
[2] https://en.wikipedia.org/wiki/User_story
On Fri, 14 May 2021 at 02:15, Tom Sweeney <tom.sweeney(a)redhat.com> wrote:
> Recently the community discovered that the Podman
> Whatis?(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) 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), or send an
> email to the Podman mailing list
> (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
> _______________________________________________
> Podman mailing list -- podman(a)lists.podman.io
> To unsubscribe send an email to podman-leave(a)lists.podman.io
>
_______________________________________________
Podman mailing list -- podman(a)lists.podman.io
To unsubscribe send an email to podman-leave(a)lists.podman.io
8 p.m.
New subject: Help Wanted: Podman Documentation contributors, suggestions, and more....
Erik,
Thanks for the thoughts and suggestions! Do you mind if I add them as a
reply to the GitHub Discussion to ensure we don't lose track?
Aric,
We're happy to take any and all help that you can provide. Any way that
you want to do it is fine by me. Personally I prefer smaller subject
concentrated reviews, like a single man page rather than 20, just
because I tend to be able to focus better on smaller ones. But I can
adjust and do longer reviews if that works better for you.
t
On 5/20/21 3:39 PM, Aric Renzo wrote:
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>
6:03 a.m.
New subject: Help Wanted: Podman Documentation contributors, suggestions, and more....
Hi Tom,
good idea. I shared my comment over there as well.
Best,
Erik
On Fri, 21 May 2021 at 02:00, Tom Sweeney <tom.sweeney(a)redhat.com> wrote:
Erik,
Thanks for the thoughts and suggestions! Do you mind if I add them as a
reply to the GitHub Discussion to ensure we don't lose track?
Aric,
We're happy to take any and all help that you can provide. Any way that
you want to do it is fine by me. Personally I prefer smaller subject
concentrated reviews, like a single man page rather than 20, just because I
tend to be able to focus better on smaller ones. But I can adjust and do
longer reviews if that works better for you.
t
On 5/20/21 3:39 PM, Aric Renzo wrote:
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>
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...
> [2] https://en.wikipedia.org/wiki/User_story
>
> On Fri, 14 May 2021 at 02:15, Tom Sweeney <tom.sweeney(a)redhat.com> wrote:
>
>> Recently the community discovered that the Podman
>> Whatis?(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) 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), or send an
>> email to the Podman mailing list
>> (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
>> _______________________________________________
>> Podman mailing list -- podman(a)lists.podman.io
>> To unsubscribe send an email to podman-leave(a)lists.podman.io
>>
> _______________________________________________
> Podman mailing list -- podman(a)lists.podman.io
> To unsubscribe send an email to podman-leave(a)lists.podman.io
>
5:51 a.m.
New subject: Help Wanted: Podman Documentation contributors, suggestions, and more....
Something contradicts the common sense in using Windows and MacOS client.
If Podman is CLI that can run as root and rootless I already have the
client to access Podman from any OS - SSH. I can always use ssh myUser@Host
and after authentication (!!!) by PAM , I can use Podman securely inside my
own remote session. As soon I open TCP socket I have to think about TLS,
firewall, enterprise policies, etc, and finally, call IT. The communication
plumbing and IT burden is the cost of client-server architecture. On other
hand, sshd with default configuration is part of all Linux Server software
and can be managed by IT automation.
End-point API is needed in another useful scenario - Master-Slave when
Podman runs Pontainer as a slave and needs bidirectional communication with
it.
On Fri, May 21, 2021 at 1:08 PM Erik Bernoth <erik.bernoth(a)gmail.com> wrote:
Hi Tom,
good idea. I shared my comment over there as well.
Best,
Erik
On Fri, 21 May 2021 at 02:00, Tom Sweeney <tom.sweeney(a)redhat.com> wrote:
> Erik,
>
> Thanks for the thoughts and suggestions! Do you mind if I add them as a
> reply to the GitHub Discussion to ensure we don't lose track?
>
> Aric,
>
> We're happy to take any and all help that you can provide. Any way that
> you want to do it is fine by me. Personally I prefer smaller subject
> concentrated reviews, like a single man page rather than 20, just because I
> tend to be able to focus better on smaller ones. But I can adjust and do
> longer reviews if that works better for you.
>
> t
>
> On 5/20/21 3:39 PM, Aric Renzo wrote:
>
> 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>
> 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...
>> [2] https://en.wikipedia.org/wiki/User_story
>>
>> On Fri, 14 May 2021 at 02:15, Tom Sweeney <tom.sweeney(a)redhat.com>
>> wrote:
>>
>>> Recently the community discovered that the Podman
>>> Whatis?(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) 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), or send an
>>> email to the Podman mailing list
>>> (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
>>> _______________________________________________
>>> Podman mailing list -- podman(a)lists.podman.io
>>> To unsubscribe send an email to podman-leave(a)lists.podman.io
>>>
>> _______________________________________________
>> Podman mailing list -- podman(a)lists.podman.io
>> To unsubscribe send an email to podman-leave(a)lists.podman.io
>>
>
> _______________________________________________
Podman mailing list -- podman(a)lists.podman.io
To unsubscribe send an email to podman-leave(a)lists.podman.io
1279
days inactive
1287
days old
5 comments
4 participants
participants (4)
-
Aric Renzo -
Erik Bernoth -
Pavel Sosin -
Tom Sweeney