[openstack-dev] [Neutron][LBaaS][Octavia][Docs] Need experienced contributor documentation best-practices and how-tos

Armando M. armamig at gmail.com
Fri Mar 4 01:59:15 UTC 2016

On 3 March 2016 at 16:56, Stephen Balukoff <sbalukoff at bluebox.net> wrote:

> Hello!
> I have a problem I'm hoping someone can help with: I have gone through the
> task of completing a shiny new feature for an openstack project, and now
> I'm trying to figure out how to get that last all-important documentation
> step done so that people will know about this new feature and use it. But
> I'm having no luck figuring out how I actually go about doing this...
> This started when I was told that in order to consider the feature
> "complete," I needed to make sure that it was documented in the openstack
> official documentation. I wholeheartedly agree with this: If it's not
> documented, very few people will know about it, let alone use it. And few
> things make an open-source contributor more sad than the idea that the work
> they've spent months or years completing isn't getting used.
> So... No problem! I'm an experienced OpenStack developer, and I just spent
> months getting this major new feature through my project's gauntlet of an
> approval process. How hard could documenting it be, right?
> So in the intervening days I've been going through the openstack-manuals,
> openstack-doc-tools, and other repositories, trying to figure out where I
> make my edits. I found both the CLI and API reference in the
> openstack-manuals repository... but when I went to edit these files, I
> noticed that there's a comment at the top stating they are auto-generated
> and shouldn't be edited? It seemed odd to me that the results of something
> auto-generated should be checked into a git repository instead of the
> configuration which creates the auto-generated output... but it's not my
> project, right?
> Anyway, so then I went to try to figure out how I get this auto-generated
> output updated, and haven't found much (ha!) documented on the process...
> when I sought help from Sam-I-Am, I was told that these essentially get
> generated once per release by "somebody." So...  I'm done, right?
> Well... I'm not so sure. Yes, if the CLI and API documentation gets
> auto-generated from the right sources, we should be good to go on that
> front, but how can I be sure the automated process is pulling this
> information from the right place? Shouldn't there be some kind of
> continuous integration or jenkins check which tests this that I can look
> at? (And if such a thing exists, how am I supposed to find out about it?)
> Also, the new feature I've added is somewhat involved, and it could
> probably use another document describing its intended use beyond the CLI /
> API ref. Heck, we already created on in the OpenStack wiki... but I'm also
> being told that we're trying to not rely on the wiki as much, per se, and
> that anything in the wiki really ought to be moved into the "official"
> documentation canon.
> So.... I'm at a loss. I'm a big fan of documentation as a communication
> tool, and I'm an experienced OpenStack developer, but when I look in the
> manual for how to contribute to the OpenStack documentation, I find a guide
> that wants to walk me through setting up gerrit... and very little targeted
> toward someone who already knows that, but just needs to know the actual
> process for updating the manual (and which part of the manual should be
> updated).
> When I went back to Sam-I-Am about this, this spawned a much larger
> discussion and he suggested I bring this up on the mailing list because
> there might be some "big picture" issues at play that should get a larger
> discussion. So... here I am.
> Here's what I think the problem is:
> * We want developers to document the features they add or modify
> * We want developers to provide good user, operator, etc. documentation
> that actual users, operators, etc. can use to understand and use the
> software we're writing.
> * We even go so far as to say that a feature is not complete unless it has
> this documentation (which I agree with)

If you agree with this, why do you bring it up twice? :)

> * With a rather small openstack-docs contributor team, we want to automate
> as much as possible, and rely on the docs team to *edit* documentation
> written by developers instead of writing the docs themselves (which is more
> time consuming for the docs team to do, and may miss important things only
> the developers know about.)
> But:
> * We don't actually provide much help to the developers to know how to do
> this. We have plenty for people who are new to OpenStack to get started
> with gerrit--  but there doesn't seem to be much practical help on where to
> get started, as an experienced contributor to other projects, on the actual
> task of updating the manual.
> And I would wager:
> * We don't seem to have many automated tools that tie into the jenkins
> gate checks to make sure that new features are properly documented.
> * We need something better than the 'APIImpact' and 'DocImpact' flags you
> can add to a commit message which generate docs project bug reports These
> are post-hoc back-filling at best, and as I understand it, often mean that
> some poor schmuck on the docs team will probably be the one who ends up
> writing the docs for the feature the developer added, probably without the
> developer's help.
> Please understand: I know that big strides have been made in the right
> direction here recently, and I know that the docs team is both small and
> under-appreciated. For example, the move from XML-based documentation to
> .rst based documentation is a huge step in a direction that will prevent
> most developers from wanting to gouge their own eyes out anymore when it
> comes to writing documentation (though in my searching over the last few
> days I did find one api reference repository where it looked like people
> are actually editing raw XML and submitting this through the gerrit review
> process... please tell me this is not actually still the state of affairs!)
> Also, I certainly don't blame the docs team for the history of how we got
> to where we are today. I'm pretty sure everyone on that (and most) projects
> is truly here to make the OpenStack world a better place and is working
> hard to make that happen. Nobody is trying to burn the house down.
> But I think there are some flames that need extinguishing. I'm writing
> this e-mail because I think we've got some additional steps that need to be
> taken to actually help experienced openstack contributors know *how* they
> go about updating the openstack docs. It's not that we aren't willing to
> write documentation (well, I don't think most are unwilling), it's that the
> process for doing this seems extremely obfuscated.
> Ideally, I would like to see a practical and relatively short how-to guide
> along the lines of: "The shiny new feature you added to your OpenStack
> project has merged. Congratulations! Here's how you update the manual..."
> This should be written by someone already very familiar with the OpenStack
> documentation system. This practical guide would provide answers for:
> * How to actually ensure that API / CLI documentation is updated (if it's
> actually automated, and what the process for that is so that others can
> check.)
> * Criteria to know when more documentation is required than just API / CLI
> reference updates
> * Where to put this more extensive documentation.
> * Other non-intuitive information you should know (eg. what image format
> diagrams should be in, and best practices for uploading them, plus style
> guides for the images)
> Even more ideally, I would like to see a practical how-to guide along the
> lines of: "So you've started a new OpenStack project. Here's how to make
> sure it plays nice with the documentation system..." This would provide
> answers for:
> * How to set up automated tests to ensure documentation meets
> machine-discernable standards for the openstack manual (eg. pep8 for docs
> with specific style-enforcement included)
> * How to set up automated tests to ensure that documentation is either
> imported from your project to the OpenStack manual (less ideal, I know--
> coders are coders and not writers for a reason), or that there are hooks
> from the openstack manual into your project which flag and potentially
> block merges of insufficiently-documented changes (ie. something better
> than adding 'APIImpact' and 'DocImpact' to your commit message and hoping
> somebody comes along and documents it at some point).
> * Best practices for things like where to put the documentation, how and
> when to require release notes, documentation templates with the proper
> style, where to put sample config files so they get automatically slurped
> into the openstack manual, etc.
> * How to know if certain types of documentation are inappropriate for the
> openstack manual, and best practices on where to put this, if not in the
> manual.
> I fully admit that it's possible the above may already exist scattered in
> various places in the current documentation structure. However, I can tell
> you from my experience in the several OpenStack projects I've contributed
> to, that it is apparently not easily located or consumed because very few
> of the experienced contributors I work with have any clue about much of the
> above.
> Please also note that I am *NOT* volunteering to write the above documents
> per se: The above docs need to be written by someone actually familiar with
> the documentation system. But it will be effort well spent, because when
> developers actually do start contributing documentation along with their
> new code, you'll get to spend more time editing those documentation
> contributions than writing them from scratch yourself. And everyone wins
> then because the OpenStack documentation becomes more complete and sucks
> less.
> In any case, I am certainly willing to provide feedback on the above
> suggested how-to guides, should someone decide to write them.

To start off, my humble suggestion would be to be kind and provide a TL;DR
before going in such depth, otherwise there's a danger of missing the
opportunity to reach out the right audience. I read this far because I felt
I was called into question (after all I am the one 'imposing' the
documentation requirement on the features we are delivering in Mitaka)!

That said, If you are a seasoned LBaaS developer and you don't know where
LBaaS doc is located or how to contribute, that tells me that LBaaS docs
are chronically neglected, and the links below are a proof of my fear.

[1] is broken, and a search on docs.openstack.org yields [2,3,4].

[4] is really aimed at developers only, while [2,3] leave an untrained eye
wondering if details are v1 or v2. Anyhow I digress...

In a nutshell, this is a rather disastrous. Other Neutron developers
already contribute successfully to user docs [5]. Most of it is already
converted to rst and the tools you're familiar with are the ones used to
produce content (like specs).

My suggestion would be to forge your own path, and identify a place in the
networking-guide where to locate some relevant content that describe
LBaaS/Octavia: deployment architecture, features, etc. This is a long
journey, that requires help from all parties, but I believe that the
initiative needs to be driven from the LBaaS team as they are the custodian
of the knowledge.

I fear that if none of the LBaaS core members steps up and figure this out,
LBaaS will continue to be something everyone would like to adopt but no-one
knows how to, at least not by tapping directly at the open source faucet.

My 2c,

[1] http://docs.openstack.org/developer/neutron-lbaas/
[2] http://docs.openstack.org/liberty/networking-guide/adv_config_LBaaS.html
[3] http://docs.openstack.org/admin-guide-cloud/networking_introduction.html
[5] https://bugs.launchpad.net/neutron/+bugs?field.tag=doc

> Stephen
> P.S. I still have no idea how I go about updating the manual for the major
> features that we added to neutron-lbaas and Octavia in this cycle.
> --
> Stephen Balukoff
> Principal Technologist
> Blue Box, An IBM Company
> www.blueboxcloud.com
> sbalukoff at blueboxcloud.com
> 206-607-0660 x807
> __________________________________________________________________________
> 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/20160303/e024886e/attachment.html>

More information about the OpenStack-dev mailing list