[all][docs] season of docs

Donny Davis donny at fortnebula.com
Thu May 23 16:55:40 UTC 2019


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 at 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:
> > >
> > > https://jacobian.org/2009/nov/10/what-to-write/
> >
> > 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
> >
> >
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20190523/13056d9c/attachment.html>


More information about the openstack-discuss mailing list