[openstack-dev] The future of OpenStack documentation

Matt Kassawara mkassawara at gmail.com
Mon Jul 11 22:26:30 UTC 2016


Andreas,

I consider the API documentation and installation guide rather complex for
initial content to move to project repositories and evaluate the results.
However, we're seeing rather strong adoption of moving API documentation
which I think predicts adoption of moving operator/user documentation more
than the installation guide. Regardless of outcome, the API documentation
caters to a smaller audience with at least some knowledge of OpenStack
and/or development experience, thus having less impact on adoption of
OpenStack. On the other hand, the installation guide is extremely popular
and caters to a larger audience with little (if any) prior knowledge of
OpenStack that expects the procedures to work with minimal frustration.
Victimizing this audience hinders adoption of OpenStack and may cast the
wrong impression of moving content into project repositories.

On Mon, Jul 11, 2016 at 3:52 PM, Michael Johnson <johnsomor at gmail.com>
wrote:

> I support putting infrastructure in place to allow the project
> documentation to be in the project's repository.  We had problems in
> the Mitaka release with documentation getting deleted without the
> project team knowing it was happening until users were asking us where
> the documentation was located.
>
> Having it in the repository makes it easier to review that the
> required documentation updates are being made and gives the project
> team visibility to changes in the documentation.
>
> Michael
>
>
> On Sun, Jul 10, 2016 at 10:31 PM, Andreas Jaeger <aj at suse.com> wrote:
> >
> > With Install Guide and API references, we had specific problems to
> > solve. Which ones do you see exactly with other guides?
> >
> > Also, before we discuss moving further documentation around, I'd like to
> > see first how the API references and Install guides work out and what we
> > need to improve there - before discussing next steps,
> >
> > Andreas
> > --
> >  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: 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
> >
> >
> >
> __________________________________________________________________________
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe:
> OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160711/ac7f0c35/attachment.html>


More information about the OpenStack-dev mailing list