[openstack-dev] The future of OpenStack documentation

Matt Kassawara mkassawara at gmail.com
Wed Jul 13 15:52:45 UTC 2016


The configuration reference essentially uses a script to parse help strings
from code in project repositories. Occasionally, the documentation team
augments content beyond what the automation provides. However, these
content augmentations, the script, and schedule for running the script
belong to the documentation team. Moving control of these items to projects
would likely yield a more robust configuration reference, particularly
regarding nuances of each project.

Speaking of help strings, I see a conflict between providing sufficient
content and preventing bloat of example configuration files. At the last
summit, I suggested implementing two types of help strings... one long and
one short. The configuration reference pulls the long string and the
configuration file generator pulls the short string. If this idea makes
sense, moving the configuration reference to project repositories would
potentially enable each project to implement such changes at its own pace.

On Wed, Jul 13, 2016 at 8:11 AM, Markus Zoeller <mzoeller at linux.vnet.ibm.com
> wrote:

> On 11.07.2016 00:02, Steve Martinelli wrote:
> > I personally like this solution, it seems much more scalable. This
> follows
> > the same pattern of the API docs (moving the content to project repos),
> > which puts the onus back on the project team to maintain and create
> > documentation. I'm also hoping this results in less duplication between
> the
> > guides and the keystone developer docs (the latter of which start to
> stray
> > from "developer" docs and begin to look like "user" docs.
>
> After reading this, the "configuration reference" comes to my mind.
> Having the api-ref and the config-ref at one place, near the code, seems
> logical to me. Nova put a lot of effort into providing valuable help
> text for the config options in the last months. We should also make sure
> that it will result in a good manual, which could be easier if it's
> in-tree, near the code.
>
> --
> Regards, Markus Zoeller (markus_z)
>
> > The folks that contribute to the keystone guides today would still be
> very
> > welcomed to continue to contribute once/if the switch is made.
> >
> > On Fri, Jul 8, 2016 at 5:02 PM, Matt Kassawara <mkassawara at gmail.com>
> wrote:
> >
> >> Currently, OpenStack provides central documentation (primarily in the
> >> openstack-manuals repository) for operators and users. The single
> location
> >> and consistent structure eases audiences of various technical expertise
> >> into OpenStack, typically operators and users rather than developers.
> >> Although I'm not a fan of the word "product", increasingly less
> technical
> >> audiences are learning about OpenStack and tend to compare it with other
> >> cloud infrastructure products. Such audiences expect a coherent,
> relatively
> >> mature product to easily evaluate, usually via proof-of-concept. Upon
> >> deciding to implement OpenStack, the central documentation attempts to
> >> gracefully lead them toward a production deployment that meets or
> exceeds
> >> requirements and expectations.
> >>
> >> However, since I began contributing to OpenStack documentation around
> the
> >> Havana release, I am seeing many projects, particularly core projects,
> >> trending toward more independence from other projects including central
> >> documentation. For operator and user documentation, a couple of projects
> >> contribute to the central documentation repository, some projects
> >> contribute to their own repositories, and an alarmingly large number of
> >> projects simply do not contribute such documentation and assume that all
> >> audiences involve developers. These differences lead to an increasingly
> >> negative overall experience for the audiences that OpenStack needs to
> >> increase adoption/growth and maintain the existing deployment base.
> >>
> >> As a contributor to central documentation and one or more other projects
> >> including neutron, I see the problems from both sides and don't
> >> particularly blame either party for them. Some politics, some technical,
> >> some a lack of resources, and some just a general misunderstanding about
> >> documentation. However, I think we need to develop a solution that works
> >> for both parties and ultimately benefits our audiences.
> >>
> >> One potential solution essentially involves moving operator and user
> >> documentation into project repositories (similar to developer
> >> documentation) and using infrastructure to coherently present it on
> >> docs.openstack.org which achieves the following goals:
> >>
> >> 1) Project developers can contribute documentation and code in the same
> >> patch, thus avoiding two different review queues and reviewers with
> >> different motivations and guidelines.
> >> 2) Project developers can either work directly or via liaison with one
> or
> >> more documentation team members to improve documentation components
> during
> >> development or after merging technically accurate content.
> >> 3) Rather than attempting to document all projects with little (if any)
> >> assistance from those projects, the primary role of the documentation
> team
> >> becomes managing overall organization/presentation of documentation and
> >> assisting projects with their contributions.
> >>
> >> We're seeing decent adoption of moving API documentation into project
> >> repositories, so I want to initiate some discussion about moving
> additional
> >> documentation (or other options) prior to mid-cycles (including ops) and
> >> the next summit.
> >>
> >> Matt
> >>
> >>
> __________________________________________________________________________
> >> 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
> >
>
>
>
> __________________________________________________________________________
> 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/20160713/4056b361/attachment.html>


More information about the OpenStack-dev mailing list