Open Stack

Excerpts from Matt Kassawara's message of 2016-07-13 09:52:45 -0600:
> 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.

oslo.config already includes support for showing option values in
sphinx-processed documentation. See
http://docs.openstack.org/developer/oslo.config/sphinxext.html for
instructions on the directives, and
http://docs.openstack.org/developer/oslo.messaging/opts.html for an
example of what it looks like rendered into HTML. You could experiment
with this the existing developer documentation and if project teams
agree it makes sense we could start setting up a separate reference
guide in each repo.

OTOH, sometimes configuring an application actually requires dealing
with a deliverable that is spread across multiple repositories.
Which is why at the summit we discussed updating the config generator
to produce a format that is easier to parse (YAML, probably) and
then use those files to produce the central config reference guide
(or multiple guides).  With a periodic job to propose patches to
the guide repo, it could stay very close to up to date more or less
automatically. Some of the other things I've been doing this cycle
have delayed me starting on this, but I'm happy to share my ideas
in more detail with anyone who wants to pick it up and work on it.

> 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
> >