Open Stack

[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 at 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 at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20190410/e3ff667c/attachment.html>