[all][docs] season of docs
Hi there:
It seems like Google has come up with a new somewhat-GSoC-like idea but focused on documentation. I think it could be a good opportunity for the documentation team (or any specific team actually, coordinated with docs) to be part of this.
https://opensource.googleblog.com/2019/03/introducing-season-of-docs.html
I'm not sure if the team has the amount of resources, but it seems they should be able to apply to this. Does this seem like something that might help the team more (or perhaps a specific project, coordinating with the docs team) to apply for this?
Thanks, Mohammed
I think it would be a great idea if we can find someone to be our coordinator. In the past when I've helped out with the Google Summer of Code, the application has been a fair bit of work, but maybe this one is different? I haven't looked yet. I can try to help support whoever wants to coordinate this, but I don't have time to be the primary point of contact.
-Kendall (diablo_rojo)
On Mon, Mar 11, 2019 at 9:30 AM Mohammed Naser mnaser@vexxhost.com wrote:
Hi there:
It seems like Google has come up with a new somewhat-GSoC-like idea but focused on documentation. I think it could be a good opportunity for the documentation team (or any specific team actually, coordinated with docs) to be part of this.
https://opensource.googleblog.com/2019/03/introducing-season-of-docs.html
I'm not sure if the team has the amount of resources, but it seems they should be able to apply to this. Does this seem like something that might help the team more (or perhaps a specific project, coordinating with the docs team) to apply for this?
Thanks, Mohammed
-- Mohammed Naser — vexxhost
D. 514-316-8872 <(514)%20316-8872> D. 800-910-1726 ext. 200 <(800)%20910-1726> E. mnaser@vexxhost.com W. http://vexxhost.com
On Tue, 2019-03-12 at 14:42 -0700, Kendall Nelson wrote:
I think it would be a great idea if we can find someone to be our coordinator. In the past when I've helped out with the Google Summer of Code, the application has been a fair bit of work, but maybe this one is different? I haven't looked yet. I can try to help support whoever wants to coordinate this, but I don't have time to be the primary point of contact. -Kendall (diablo_rojo)
This sounds like something the docs team (and me specifically) could take point on. I'm happy to look into what's required and reach out to people as necessary. Is there anything documented regarding the previous Summer of Code applications though?
Stephen
On Mon, Mar 11, 2019 at 9:30 AM Mohammed Naser mnaser@vexxhost.com wrote:
Hi there:
It seems like Google has come up with a new somewhat-GSoC-like idea
but focused on documentation. I think it could be a good opportunity
for the documentation team (or any specific team actually, coordinated
with docs) to be part of this.
https://opensource.googleblog.com/2019/03/introducing-season-of-docs.html
I'm not sure if the team has the amount of resources, but it seems
they should be able to apply to this. Does this seem like something
that might help the team more (or perhaps a specific project,
coordinating with the docs team) to apply for this?
Thanks,
Mohammed
We've only been selected on time previously I think? The application process was pretty involved from what I recall. I will dig around and see if I can find anything from our last application and send it over if I discover anything.
Happy to try to help with the application too if you want an extra set of eyes/hands.
-Kendall (diablo_rojo)
On Wed, Mar 20, 2019 at 2:51 AM Stephen Finucane sfinucan@redhat.com wrote:
On Tue, 2019-03-12 at 14:42 -0700, Kendall Nelson wrote:
I think it would be a great idea if we can find someone to be our coordinator. In the past when I've helped out with the Google Summer of Code, the application has been a fair bit of work, but maybe this one is different? I haven't looked yet. I can try to help support whoever wants to coordinate this, but I don't have time to be the primary point of contact.
-Kendall (diablo_rojo)
This sounds like something the docs team (and me specifically) could take point on. I'm happy to look into what's required and reach out to people as necessary. Is there anything documented regarding the previous Summer of Code applications though?
Stephen
On Mon, Mar 11, 2019 at 9:30 AM Mohammed Naser mnaser@vexxhost.com wrote:
Hi there:
It seems like Google has come up with a new somewhat-GSoC-like idea but focused on documentation. I think it could be a good opportunity for the documentation team (or any specific team actually, coordinated with docs) to be part of this.
https://opensource.googleblog.com/2019/03/introducing-season-of-docs.html
I'm not sure if the team has the amount of resources, but it seems they should be able to apply to this. Does this seem like something that might help the team more (or perhaps a specific project, coordinating with the docs team) to apply for this?
Thanks, Mohammed
On 21/03/2019 01:58, Kendall Nelson wrote: We've only been selected on time previously I think? The application process was pretty involved from what I recall. I will dig around and see if I can find anything from our last application and send it over if I discover anything.
Happy to try to help with the application too if you want an extra set of eyes/hands.
Ditto. I love these applications and Outreachy was really successful! (well, sorta, long story)
-Kendall (diablo_rojo)
On Wed, Mar 20, 2019 at 2:51 AM Stephen Finucane <sfinucan@redhat.commailto:sfinucan@redhat.com> wrote: On Tue, 2019-03-12 at 14:42 -0700, Kendall Nelson wrote: I think it would be a great idea if we can find someone to be our coordinator. In the past when I've helped out with the Google Summer of Code, the application has been a fair bit of work, but maybe this one is different? I haven't looked yet. I can try to help support whoever wants to coordinate this, but I don't have time to be the primary point of contact.
-Kendall (diablo_rojo)
This sounds like something the docs team (and me specifically) could take point on. I'm happy to look into what's required and reach out to people as necessary. Is there anything documented regarding the previous Summer of Code applications though?
Stephen
On Mon, Mar 11, 2019 at 9:30 AM Mohammed Naser <mnaser@vexxhost.commailto:mnaser@vexxhost.com> wrote: Hi there:
It seems like Google has come up with a new somewhat-GSoC-like idea but focused on documentation. I think it could be a good opportunity for the documentation team (or any specific team actually, coordinated with docs) to be part of this.
https://opensource.googleblog.com/2019/03/introducing-season-of-docs.html
I'm not sure if the team has the amount of resources, but it seems they should be able to apply to this. Does this seem like something that might help the team more (or perhaps a specific project, coordinating with the docs team) to apply for this?
Thanks, Mohammed
[Top posting] Petr (Kovar) has kindly put me in touch with folks within Red Hat who have worked on this in the past for other projects. They're able to help with getting the submission out the door and have pointed to Gnome's submission as a good example of what we need to do here: https://wiki.gnome.org/Outreach/SeasonofDocs Based of that, I guess the next steps are figuring out what projects need the most help and putting together a list of ideas that we can submit. I can only really speak for nova and oslo. For nova, I'd like to see us better align with the documentation style used in Django, which is described in the below article: https://jacobian.org/2009/nov/10/what-to-write/ The documentation structure we use doesn't allow us to map to this directly but I do think there are some easy gains to be made: * More clearly delineate between admin-facing (/admin) and user-facing (/user) docs * Expand the how-to docs we have to better explain common user and admin operations, such as rebooting instances, rebuilding, attaching interfaces, etc.
On top of that, there are some general cleanup things that need to happen and just haven't. * [Technical] Audit our reference guide, which explains concepts like cells v2, to see if these make sense to someone who's not in the trenches * Generally examine the structure of the docs to see how easy it is to find stuff (fwiw, I struggle to find things without Google so this is probably a bad sign)
For oslo, I think our issue is less about documentation and more about marketing (very few people outside of OpenStack know that reno is a thing, for example, or that oslo.config exists and is as powerful as it is) so there's nothing I'd really submit here. I'm willing to debate that though, if someone disagrees. Does anyone else have anything they'd like to get help with? If so, please let me know (here or on IRC) and we can feed that into the process. Stephen On Thu, 2019-03-21 at 10:07 +0000, Alexandra Settle wrote:
On 21/03/2019 01:58, Kendall Nelson wrote:
We've only been selected on time previously I think? The application process was pretty involved from what I recall. I will dig around and see if I can find anything from our last application and send it over if I discover anything.
Happy to try to help with the application too if you want an extra set of eyes/hands.
Ditto. I love these applications and Outreachy was really successful! (well, sorta, long story)
-Kendall (diablo_rojo)
On Wed, Mar 20, 2019 at 2:51 AM Stephen Finucane < sfinucan@redhat.com> wrote:
On Tue, 2019-03-12 at 14:42 -0700, Kendall Nelson wrote:
I think it would be a great idea if we can find someone to be our coordinator. In the past when I've helped out with the Google Summer of Code, the application has been a fair bit of work, but maybe this one is different? I haven't looked yet. I can try to help support whoever wants to coordinate this, but I don't have time to be the primary point of contact.
-Kendall (diablo_rojo)
This sounds like something the docs team (and me specifically) could take point on. I'm happy to look into what's required and reach out to people as necessary. Is there anything documented regarding the previous Summer of Code applications though?
Stephen
On Mon, Mar 11, 2019 at 9:30 AM Mohammed Naser < mnaser@vexxhost.com> wrote:
Hi there:
It seems like Google has come up with a new somewhat-GSoC- like idea
but focused on documentation. I think it could be a good opportunity
for the documentation team (or any specific team actually, coordinated
with docs) to be part of this.
https://opensource.googleblog.com/2019/03/introducing-season-of-docs.html
I'm not sure if the team has the amount of resources, but it seems
they should be able to apply to this. Does this seem like something
that might help the team more (or perhaps a specific project,
coordinating with the docs team) to apply for this?
Thanks,
Mohammed
On 2019-04-10 11:45:39 +0100 (+0100), Stephen Finucane wrote: [...]
I guess the next steps are figuring out what projects need the most help and putting together a list of ideas that we can submit. I can only really speak for nova and oslo.
[...]
In the last Security SIG meeting we discussed (in the context of the TC's "help wanted" list) how most of the help we need is documentation related.
We need Security Analysis documents for a lot of projects, and reviewers for many of the ones already proposed too:
https://docs.openstack.org/security-analysis/latest/ https://review.openstack.org/#/q/project:openstack/security-analysis+is:open https://opendev.org/openstack/security-analysis/
The Security Guide doesn’t seem to have been updated since Pike, so it’s a good 1.5 years behind. Having someone step through what's there and confirm or refresh it for Stein would be awesome:
https://docs.openstack.org/security-guide/ https://opendev.org/openstack/security-doc/
The documentation we have on secure coding practices is fairly light and could do with more content:
https://security.openstack.org/#secure-development-guidelines
We could also use help with writing security notes and triaging the outstanding OSSN backlog:
https://wiki.openstack.org/wiki/Security_Notes https://wiki.openstack.org/wiki/Security/Security_Note_Process https://bugs.launchpad.net/ossn
Much of the above likely requires folks with at least some information security background or interest, but it's a really great place to improve the overall security posture of OpenStack across the board.
On Wed, 2019-04-10 at 11:45 +0100, Stephen Finucane wrote:
[Top posting]
Petr (Kovar) has kindly put me in touch with folks within Red Hat who have worked on this in the past for other projects. They're able to help with getting the submission out the door and have pointed to Gnome's submission as a good example of what we need to do here:
https://wiki.gnome.org/Outreach/SeasonofDocs
Based of that, I guess the next steps are figuring out what projects need the most help and putting together a list of ideas that we can submit.
I can only really speak for nova and oslo. For nova, I'd like to see us better align with the documentation style used in Django, which is described in the below article:
https://jacobian.org/2009/nov/10/what-to-write/
The documentation structure we use doesn't allow us to map to this directly but I do think there are some easy gains to be made:
More clearly delineate between admin-facing (/admin) and user-facing (/user) docsExpand the how-to docs we have to better explain common user and admin operations, such as rebooting instances, rebuilding, attaching interfaces, etc. On top of that, there are some general cleanup things that need to happen and just haven't.
[Technical] Audit our reference guide, which explains concepts like cells v2, to see if these make sense to someone who's not in the trenchesGenerally examine the structure of the docs to see how easy it is to find stuff (fwiw, I struggle to find things without Google so this is probably a bad sign) For oslo, I think our issue is less about documentation and more about marketing (very few people outside of OpenStack know that reno is a thing, for example, or that oslo.config exists and is as powerful as it is) so there's nothing I'd really submit here. I'm willing to debate that though, if someone disagrees.
Does anyone else have anything they'd like to get help with? If so, please let me know (here or on IRC) and we can feed that into the process.
Stephen
Just to close this off, we never got to finish the application for this. It was quite involved, as promised, and Summit/PTG work took priority. Hopefully we'll be able to try again next year. Thanks to all who provided suggestions for things to work on. Stephen
On Thu, 2019-03-21 at 10:07 +0000, Alexandra Settle wrote:
On 21/03/2019 01:58, Kendall Nelson wrote:
We've only been selected on time previously I think? The application process was pretty involved from what I recall. I will dig around and see if I can find anything from our last application and send it over if I discover anything.
Happy to try to help with the application too if you want an extra set of eyes/hands.
Ditto. I love these applications and Outreachy was really successful! (well, sorta, long story)
-Kendall (diablo_rojo)
On Wed, Mar 20, 2019 at 2:51 AM Stephen Finucane < sfinucan@redhat.com> wrote:
On Tue, 2019-03-12 at 14:42 -0700, Kendall Nelson wrote:
I think it would be a great idea if we can find someone to be our coordinator. In the past when I've helped out with the Google Summer of Code, the application has been a fair bit of work, but maybe this one is different? I haven't looked yet. I can try to help support whoever wants to coordinate this, but I don't have time to be the primary point of contact.
-Kendall (diablo_rojo)
This sounds like something the docs team (and me specifically) could take point on. I'm happy to look into what's required and reach out to people as necessary. Is there anything documented regarding the previous Summer of Code applications though?
Stephen
On Mon, Mar 11, 2019 at 9:30 AM Mohammed Naser < mnaser@vexxhost.com> wrote:
Hi there:
It seems like Google has come up with a new somewhat-GSoC- like idea
but focused on documentation. I think it could be a good opportunity
for the documentation team (or any specific team actually, coordinated
with docs) to be part of this.
https://opensource.googleblog.com/2019/03/introducing-season-of-docs.html
I'm not sure if the team has the amount of resources, but it seems
they should be able to apply to this. Does this seem like something
that might help the team more (or perhaps a specific project,
coordinating with the docs team) to apply for this?
Thanks,
Mohammed
Just to close this off, we never got to finish the application for this. It was quite involved, as promised, and Summit/PTG work took priority. Hopefully we'll be able to try again next year. Thanks to all who provided suggestions for things to work on.
I assume this doesn't stop us from making docs a focus this release, and from leaning on guidelines like:
I can only really speak for nova and oslo. For nova, I'd like to see us better align with the documentation style used in Django, which is described in the below article:
As you know (but for others' awareness) Nova has a cycle theme for this [1]. Just need some bodies to throw at it...
efried
[1] https://review.opendev.org/#/c/657171/2/priorities/train-priorities.rst@37
On Thu, 2019-05-23 at 10:33 -0500, Eric Fried wrote:
Just to close this off, we never got to finish the application for this. It was quite involved, as promised, and Summit/PTG work took priority. Hopefully we'll be able to try again next year. Thanks to all who provided suggestions for things to work on.
I assume this doesn't stop us from making docs a focus this release, and from leaning on guidelines like:
Not at all. This was just a chance to get even more eyes on this, but we should be able to make a good hand of this ourselves over the course of the cycle.
I can only really speak for nova and oslo. For nova, I'd like to see us better align with the documentation style used in Django, which is described in the below article:
As you know (but for others' awareness) Nova has a cycle theme for this [1]. Just need some bodies to throw at it...
efried
[1] https://review.opendev.org/#/c/657171/2/priorities/train-priorities.rst@37
Right now we have several docs to maintain, and users have several docs to sort through. My observation of the issue has been that beginners don't know what they don't know. There has to be a way of lowering the barrier to entry without rendering the docs useless for people past their first deployment. In the context of this discussion I am talking about all of the guides, but not really the content. The content we have really is not that bad. I am more interested about how that content is found and presented to the user.
Is there a facility we can use that would just scope the docs to a point of view? Maybe like a tag in sphinx?
Docs and "cloudy understanding" have been the barrier to entry in Openstack for many shops for a long time, so its a great conversation for us to be having.
~/Donny Davis
On Thu, May 23, 2019 at 11:45 AM Stephen Finucane sfinucan@redhat.com wrote:
On Thu, 2019-05-23 at 10:33 -0500, Eric Fried wrote:
Just to close this off, we never got to finish the application for this. It was quite involved, as promised, and Summit/PTG work took priority. Hopefully we'll be able to try again next year. Thanks to all who provided suggestions for things to work on.
I assume this doesn't stop us from making docs a focus this release, and from leaning on guidelines like:
Not at all. This was just a chance to get even more eyes on this, but we should be able to make a good hand of this ourselves over the course of the cycle.
I can only really speak for nova and oslo. For nova, I'd like to see us better align with the documentation style used in Django, which is described in the below article:
As you know (but for others' awareness) Nova has a cycle theme for this [1]. Just need some bodies to throw at it...
efried
[1]
https://review.opendev.org/#/c/657171/2/priorities/train-priorities.rst@37
participants (7)
-
Alexandra Settle
-
Donny Davis
-
Eric Fried
-
Jeremy Stanley
-
Kendall Nelson
-
Mohammed Naser
-
Stephen Finucane