[ops][docs] The Contributor Guide: Ops Feedback Session Summary
Hello! For the long version, feel free to look over the etherpad[1]. It should be noted that this session was in relation to the operator section of the contributor guide, not the operations guide, though they should be closely related and link to one another. Basically the changes requested can be boiled down to two types of changes: cosmetic and missing content. Cosmetic Changes: - Timestamps so people can know when the last change was made to a given doc (dhellmann volunteered to help here)[2] - Floating bug report button and some mechanism for auto populating which page a bug is on so that the reader doesn’t have to know what rst file in what repo has the issue to file a bug[3] - Maybe not cosmetic exactly, but it was requested that the entirety of the contributor guide be translated into as many languages as possible (stevenK volunteered to help get the framework setup so that things could be imported into Zanata for translation)[4] - Link to source somewhere on the page so those interested in fixing issues that don’t know the repo structure can find and fix issues right away[5] Missing Content: - Links to the docs in the Operator guide (HA guide, etc)[6] - A guide to ‘I fixed this bug locally, how do I get it upstream?’[7] If there are any unclaimed items you are interested in working on, please do! The contributor guide work items are tracked in StoryBoard here[8]! -Kendall (diablo_rojo) [1] https://etherpad.openstack.org/p/BER-Contrib-Guide-Ops [2] https://storyboard.openstack.org/#!/story/2004436 [3] https://storyboard.openstack.org/#!/story/2004437 [4] https://storyboard.openstack.org/#!/story/2004438 [5] https://storyboard.openstack.org/#!/story/2004439 [6] https://storyboard.openstack.org/#!/story/2004441 [7] https://storyboard.openstack.org/#!/story/2004442 [8]https://storyboard.openstack.org/#!/project/openstack/contributor-guide
On 11/27/18 4:38 PM, Kendall Nelson wrote:
Hello!
For the long version, feel free to look over the etherpad[1].
It should be noted that this session was in relation to the operator section of the contributor guide, not the operations guide, though they should be closely related and link to one another.
Basically the changes requested can be boiled down to two types of changes: cosmetic and missing content.
Cosmetic Changes:
*
Timestamps so people can know when the last change was made to a given doc (dhellmann volunteered to help here)[2]
*
Floating bug report button and some mechanism for auto populating which page a bug is on so that the reader doesn’t have to know what rst file in what repo has the issue to file a bug[3]
This is something probably for openstackdocstheme to have it everywhere. With launchpad, the information on RST file is part of the "Report a bug" process. We do not have an equivelent "Report a bug" process for storyboard that allows prepopulating content - otherwise, we could update openstackdocstheme to pass this on. Andreas
*
Maybe not cosmetic exactly, but it was requested that the entirety of the contributor guide be translated into as many languages as possible (stevenK volunteered to help get the framework setup so that things could be imported into Zanata for translation)[4]
*
Link to source somewhere on the page so those interested in fixing issues that don’t know the repo structure can find and fix issues right away[5]
Missing Content:
*
Links to the docs in the Operator guide (HA guide, etc)[6]
*
A guide to ‘I fixed this bug locally, how do I get it upstream?’[7]
If there are any unclaimed items you are interested in working on, please do! The contributor guide work items are tracked in StoryBoard here[8]!
-Kendall (diablo_rojo)
[1] https://etherpad.openstack.org/p/BER-Contrib-Guide-Ops
[2] https://storyboard.openstack.org/#!/story/2004436
[3] https://storyboard.openstack.org/#!/story/2004437
[4] https://storyboard.openstack.org/#!/story/2004438
[5] https://storyboard.openstack.org/#!/story/2004439
[6] https://storyboard.openstack.org/#!/story/2004441
[7] https://storyboard.openstack.org/#!/story/2004442
[8]https://storyboard.openstack.org/#!/project/openstack/contributor-guide
-- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
On 2018-11-27 16:52:11 -0500 (-0500), Andreas Jaeger wrote: [...]
We do not have an equivelent "Report a bug" process for storyboard that allows prepopulating content [...]
Since https://review.openstack.org/526219 merged in February, the new story creation URL allows passing HTTP GET parameters which can include default Story title and description content along with a project ID for the initial task. This could be used with some templating to inject the file path as part of a suggested description. https://storyboard.openstack.org/#!/story/new?project_id=456&title=foo&description=bar%20baz It could stand to have a project_name parameter so that something like project_name=openstack-infra/storyboard would be possible rather than the current project_id=456 construct, but I don't think that will be tough to add if someone's interested in using it. -- Jeremy Stanley
On 11/27/18 5:52 PM, Jeremy Stanley wrote:
On 2018-11-27 16:52:11 -0500 (-0500), Andreas Jaeger wrote: [...]
We do not have an equivelent "Report a bug" process for storyboard that allows prepopulating content [...]
Since https://review.openstack.org/526219 merged in February, the new story creation URL allows passing HTTP GET parameters which can include default Story title and description content along with a project ID for the initial task. This could be used with some templating to inject the file path as part of a suggested description.
https://storyboard.openstack.org/#!/story/new?project_id=456&title=foo&description=bar%20baz
It could stand to have a project_name parameter so that something like project_name=openstack-infra/storyboard would be possible rather than the current project_id=456 construct, but I don't think that will be tough to add if someone's interested in using it.
Great, wasn't aware of it - now we need somebody to work on openstackdocstheme for that ;) I filed bug https://bugs.launchpad.net/openstack-doc-tools/+bug/1805514 for this, Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
HI all, Sorry if my question is too silly: are you going to modify the Developer's Guide too? [1]. I have some suggestions for the Starting Work on a New Project section. On the other hand, I think I could help to translate the guide to Spanish (since I'm Spanish native speaker). Let me know if you need help. Thanks, Sofia [1] https://docs.openstack.org/infra/manual/developers.html. On Tue, Nov 27, 2018 at 8:22 PM Andreas Jaeger <aj@suse.com> wrote:
On 11/27/18 5:52 PM, Jeremy Stanley wrote:
On 2018-11-27 16:52:11 -0500 (-0500), Andreas Jaeger wrote: [...]
We do not have an equivelent "Report a bug" process for storyboard that allows prepopulating content [...]
Since https://review.openstack.org/526219 merged in February, the new story creation URL allows passing HTTP GET parameters which can include default Story title and description content along with a project ID for the initial task. This could be used with some templating to inject the file path as part of a suggested description.
https://storyboard.openstack.org/#!/story/new?project_id=456&title=foo&description=bar%20baz
It could stand to have a project_name parameter so that something like project_name=openstack-infra/storyboard would be possible rather than the current project_id=456 construct, but I don't think that will be tough to add if someone's interested in using it.
Great, wasn't aware of it - now we need somebody to work on openstackdocstheme for that ;)
I filed bug https://bugs.launchpad.net/openstack-doc-tools/+bug/1805514 for this,
Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
-- Laura Sofia Enriquez Associate Software Engineer Red Hat PnT <https://www.redhat.com> Ingeniero Butty 240, Piso 14 (C1001AFB) Buenos Aires - Argentina +541143297471 (8426471) senrique@redhat.com <https://red.ht/sig>
Andreas Jaeger <aj@suse.com> writes:
On 11/27/18 4:38 PM, Kendall Nelson wrote:
Hello!
For the long version, feel free to look over the etherpad[1].
It should be noted that this session was in relation to the operator section of the contributor guide, not the operations guide, though they should be closely related and link to one another.
Basically the changes requested can be boiled down to two types of changes: cosmetic and missing content.
Cosmetic Changes:
*
Timestamps so people can know when the last change was made to a given doc (dhellmann volunteered to help here)[2]
*
Floating bug report button and some mechanism for auto populating which page a bug is on so that the reader doesn’t have to know what rst file in what repo has the issue to file a bug[3]
This is something probably for openstackdocstheme to have it everywhere.
Yes, that was the idea. We already have some code that pulls the timestamp from git in the governance repo, so I was going to move that over to the theme for better reuse. -- Doug
Doug Hellmann <doug@doughellmann.com> writes:
Andreas Jaeger <aj@suse.com> writes:
On 11/27/18 4:38 PM, Kendall Nelson wrote:
Hello!
For the long version, feel free to look over the etherpad[1].
It should be noted that this session was in relation to the operator section of the contributor guide, not the operations guide, though they should be closely related and link to one another.
Basically the changes requested can be boiled down to two types of changes: cosmetic and missing content.
Cosmetic Changes:
*
Timestamps so people can know when the last change was made to a given doc (dhellmann volunteered to help here)[2]
*
Floating bug report button and some mechanism for auto populating which page a bug is on so that the reader doesn’t have to know what rst file in what repo has the issue to file a bug[3]
This is something probably for openstackdocstheme to have it everywhere.
Yes, that was the idea. We already have some code that pulls the timestamp from git in the governance repo, so I was going to move that over to the theme for better reuse.
-- Doug
The patch to add this to the theme is in https://review.openstack.org/#/c/621690/ -- Doug
Thanks Doug! -Kendall (diablo_rojo) On Mon, Dec 3, 2018 at 12:01 PM Doug Hellmann <doug@doughellmann.com> wrote:
Doug Hellmann <doug@doughellmann.com> writes:
Andreas Jaeger <aj@suse.com> writes:
On 11/27/18 4:38 PM, Kendall Nelson wrote:
Hello!
For the long version, feel free to look over the etherpad[1].
It should be noted that this session was in relation to the operator section of the contributor guide, not the operations guide, though they should be closely related and link to one another.
Basically the changes requested can be boiled down to two types of changes: cosmetic and missing content.
Cosmetic Changes:
*
Timestamps so people can know when the last change was made to a given doc (dhellmann volunteered to help here)[2]
*
Floating bug report button and some mechanism for auto populating which page a bug is on so that the reader doesn’t have to know what rst file in what repo has the issue to file a bug[3]
This is something probably for openstackdocstheme to have it everywhere.
Yes, that was the idea. We already have some code that pulls the timestamp from git in the governance repo, so I was going to move that over to the theme for better reuse.
-- Doug
The patch to add this to the theme is in https://review.openstack.org/#/c/621690/
-- Doug
participants (5)
-
Andreas Jaeger
-
Doug Hellmann
-
Jeremy Stanley
-
Kendall Nelson
-
Sofia Enriquez