Open Stack

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

(Snipping throughout)

On 04/03/16 15:39, Stephen Balukoff wrote:
> Hello Lana!
> 
> Thank you for your prompt reply--  I found it extremely helpful!  Comments
> inline:
> 

<snip>

>>> 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?
>>
>> That 'somebody', to be more specific, is the speciality team in charge of
>> the book in question. We also do a full refresh of the scripts before each
>> release.
>>
>>
> Cool! Is that process documented anywhere? Or better yet, is there a way
> for developers to do a "check experimental" or similar operation on any
> given patch so we can see what the manual will look like after our API /
> CLI updates (presumably in said patch)?
> 

To be honest, this is seriously underdocumented, and we're well aware of that. I do know that a few people are working on rectifying that situation, and I believe that Brian Moss will have a patch up soon to add some more info to the Contributor's Guide. Docs infra (like so much other infra) has been built up over time, and it's a big beast to untangle and document. 

I'm not aware of a tool to check for automated docs updates, though, sorry.

<snip>

>> Depending on the feature and project in question, I would usually
>> recommend you add it to the appropriate documentation in your project repo.
>> These are then published to
>> http://docs.openstack.org/developer/[yourproject] and are considered
>> official OpenStack documentation.
>>
>> If you want it added to the broader OpenStack documentation (the top level
>> on the docs.openstack.org), then I suggest you open a bug, wait for a
>> docs person to triage it (we can help advise on book/chapter, etc), and
>> then create a patch against the book in the same way as you do for your
>> project. If you don't want to write it yourself, that's fine. Open the bug,
>> give as much detail as you can, and we'll take it from there.
>>
>>
> Aah--  so I knew that the Octavia documentation we've committed thus far
> showed up that way but I'd been given the impression that we were doing the
> wrong thing: That it was generally not considered a good thing to have your
> documentation live in your own custom non-openstack-manual space and that
> you should instead work to get all of it moved into the openstack manual.

Not at all, docs.openstack.org/developer is considered official, and is absolutely the right place for developer documentation :)

> 
> In any case it's good to know about how you prefer people contribute
> changes to the manual: I expected y'all to want full editorial control over
> everything the goes into the manual, but I didn't know you'd just go write
> excerpts yourself on features that developers add and then open
> documentation bug reports for. That sounds like a lot of work for you!
> 

It's what tech writers do :P


<snip>

>>
>> There's not a lot of content here to share. You commit docs in exactly the
>> same way as you commit code. If you already have the skills to commit code
>> to an OpenStack project, then you know everything you need to know to
>> commit to docs.
>>
> 
> ...except for the stuff that's in there right now that's auto-generated. :)
> I wonder if there's a better way to communicate that developers generally
> won't have to worry about updating API / CLI references manually as this is
> all auto-generated... other than having been here long enough to know
> that's the case. (FWIW, I dislike relying on tribal knowledge...)
> 

This is mentioned explicitly in the Contributor Guide: http://docs.openstack.org/contributor-guide/docs-builds.html I do acknowledge, though, that we don't go into detail on how the automation works. The best we really have at the moment is this: http://git.openstack.org/cgit/openstack/openstack-doc-tools/tree/autogenerate_config_docs/README.rst which isn't a great solution. As I mentioned earlier, we're working on it. Happy to take suggestions on where you think we should have more content around this.


<snip>

> 
> Aah-- you're right that a good portion of this is already documented there.
> Sorry-- I looked through the guide but didn't see what I was after in a lot
> of it.
> 
> I guess the piece that was missing for me here was an opinionated guideline
> on where documentation should go that is not necessarily appropriate for
> the general openstack manual. You already told me above it should go in
> project-specific documentation repositories, but perhaps it would be
> helpful to mention something about that in this contributor guide? More on
> this later...
> 

I agree that this probably isn't explicit in the Contributor Guide. I'll go ahead and do something about that this week.

It is mentioned in the Infra Guide here: http://docs.openstack.org/infra/manual/creators.html#add-link-to-your-developer-documentation

<snip>

> 
> Oh! I meant "style" in the developers' sense, not English writing style.
> (We'll have to be worried, indeed, once computers are able to reliably do
> the latter.) I was talking more of the sorts of things that pep8 is able to
> pick out:  Lines that are too long, images in formats or in sizes we don't
> allow, required sections of documents missing or using the wrong
> separators. In other words, things that are syntactically correct that the
> underlying compilation tools will allow, but that we have decided not to do
> because we have opinionated conventions and standards we want to follow
> (which are documented in the contributor's guide). That's the kind of
> "style" computers are generally great at enforcing.

Yep, we already use Jenkins for that kind of thing.

<snip>

> 
> I guess I was just trying to see if there was a simpler way that project
> cores could prevent merging code that wasn't well documented-- in other
> words, force the developer submitting code to write a first draft of what
> they think should be included in the manual for this. As it is right now,
> the core has to merge the code with a 'DocImpact' flag in the commit
> message, and then it falls off the radar-- the core may not follow-up that
> the documentation was ever written or included important subtle details.
> 
> Maybe it would be better to add a new "Doc-Change: <id>" flag that refers
> to the change ID of an update to the openstack-manuals repository that's
> under review? That way if the core thinks the change warrants an openstack
> manual update, they can force the submitter to actually get that started
> (and even near its final form) before the code is merged.
> 
> This would allow cores (who care about making sure documentation is
> updated) to enforce that policy more effectively: If a developer can't get
> their code merged without a good documentation draft, they're going to
> write the documentation.
> 
> If we had that feature, then we could lobby hard to convince cores to
> require "Doc-Change:" instead of "DocImpact" whenever an openstack manual
> update is required. :)

To be fair, this is what DocImpact started out as, and eventually it just became a blunt instrument. Every developer would add a DocImpact flag in to their patch (because every patch needs some kind of documentation), which would open a bug in the docs queue, and then walk away. This created a massive docs triaging headache.

Now we've made some changes to how DocImpact works, so that patches marked with DocImpact raise a bug in the project's bug queue. This way, they can be effectively triaged by people who understand the codebase (and, in the case of developer docs, have the appropriate permissions to land changes). People reviewing DocImpact bugs in their queues that find it impacts something in the openstack-manuals repo should just flick the bug over to us so we can handle the fix. 

In this way, we're hoping to change DocImpact from the blunt instrument it was, to a more fine-edged tool, and encourage developers to think through the effect that adding DocImpact actually has. In other words, what we're dealing with here is technical solutions to human problems. Somewhat predictably, the idea of what constitutes "well documented" is highly subjective.

> 

<snip>

> 
> See, this is one of the things I think we could improve upon:
> 
> I was around when the Octavia project was founded. We had no idea what the
> "right" way was for us to organize our repository with regard to
> documentation, let alone how to set up automated tests for things like
> whether our local manual would build. We ended up essentially stealing code
> and conventions from other openstack and stackforge projects (which often
> didn't do things consistently), also having no idea whether they were doing
> things the "right" or best way. This wasn't so much about "should our API
> reference go in this directory or that" so much as "is there a convention
> for this, and will our choice potentially cause predictable problems for
> others and/or break automated documentation compilation tools."
> 
> We also had no idea whether it was appropriate to keep documentation in our
> own repository-- we put it there as a place to keep it temporarily until
> and if the project was ever accepted into the OpenStack umbrella (at which
> point we thought we'd have to get it all into the manual somehow).
> 
> What I'd like to see on this front is some kind of opinionated guide on the
> best way to organize where documentation should go within a project, as
> well as recommendations for which tests should be set up for the same. Of
> course this won't be appropriate for every project (hence "opinionated
> guide"), but it seems to me that it would be helpful to project cores to
> have such a thing-- and would likely aid with automation and consistency of
> documentation across the umbrella of OpenStack projects.

I agree that many developers (especially developers of those groups new to the big tent) seem to think that they need to be on the top level docs.openstack.org, without necessarily understanding that docs.openstack.org/developer is usually the more appropriate place, at  least to begin with. This should probably be made more explicit both in the Infra Manual, plus anywhere that Foundation is discussing big tent inclusion.

> 
> In addition to this, I also don't find any good guideline in the
> documentation contributors' guide as to what kind of documentation is
> appropriate for the openstack manual, and which should go elsewhere. I
> realize this is also very much a judgement call-- but that's why I'd call
> it an "informed opinion."
> 
> Again, what I'm asking for here is an codified informed opinion (which is
> really all a "best practices" guide is). No strict enforcement of policy
> (unless the individual project cores want to do that), per se: Just
> guidelines y'all think that project cores should be following regarding the
> treatment of documentation within and without the OpenStack manual. We are
> more experienced than we were back then, but I suspect that even very
> mature projects could benefit from this guide (especially if best practices
> change, or as there is turnover in cores). Having that added to the
> documentation contributors' guideline would be very helpful, in my opinion!
> 

I agree. As I mentioned earlier, I'll propose a patch to the Contributor's Guide, to hopefully make this more explicit.

> 

<snip>

>>
> 
> I agree that handling docs like code is a good thing. Maybe adding the
> "Doc-Change:" feature described above could aid in that. :)
> 
> Perhaps part of the problem is that the contributors' guide has only one
> "Quickstart" page, that is aimed purely at people new to OpenStack
> contribution in general. Perhaps it would be a good thing to create two
> more quickstart pages:  One aimed at experienced contributors who
> nevertheless don't do (or haven't done) documentation updates that often,
> and another aimed at project cores which list best practices for where
> different types of documentation should go, as well as best practices for
> how to organize and test documentation kept within their own repositories
> (even if half of this just ends up being links to infra docs)?
> 
> Part of the problem with the contributors' guide as I see it right now is
> that it provides a lot of detail on specific items, but it's easy to get
> quickly overloaded in detail. The detail is definitely important, but
> without knowing where to get started, it can become frustrating (and people
> will give up-- even people who have otherwise work with gerrit every day.)
> 
> Does that make sense?
> 

Absolutely. Thank you.

> 

<snip>

>>
>> Your automated content should be here:
>> http://docs.openstack.org/liberty/config-reference/content/networking-plugin-lbaas.html
>> Please raise a bug against openstack-manuals (
>> https://launchpad.net/openstack-manuals) if that is not the case.
>>
>>
> Ok, I will do what I can to galvanize my team to make the above not suck.
> :) Given our previous discussion, I don't suppose there's an obvious way to
> figure out where a relatively new project's information ought to be
> inserted in the manual?  (Octavia is the reference implementation for
> Neutron-LBaaS, so in the operators' guide on how to set up LBaaS we're also
> going to have to describe how to set up, configure and maintain Octavia.)

I'll go out on a limb here, and suggest that maybe you need to consider some addition to the Networking Guide (http://docs.openstack.org/liberty/networking-guide/).

> 
> 
>> Octavia is documented here: http://docs.openstack.org/developer/octavia/
>> If you have content to add, propose a patch to
>> http://git.openstack.org/cgit/openstack/octavia
>>
>>
> Yep-- contributed a good portion of that myself already, actually. :)
> (Didn't know that was "kosher.")
> 

This is a really great start, and it's also a good way to draft pieces that you can consider submitting to the openstack-manuals at a later date.

> 
> 
>> If you feel these things should be documented elsewhere, please raise a
>> bug, or ping me on IRC (I'm loquacity) and we can chat further about the
>> best place for it.
>>
> 
> Cool beans! I'm "sbalukoff" on IRC and can usually be raised in the
> #openstack-lbaas channel.
> 

See you around!

L

- -- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBCAAGBQJW3NMhAAoJELppzVb4+KUy2AQH/1s0rdaYKmkCS8R/HOcCggoS
99Dh1QoNngpLOnzpVH8ElQFaRvjHBmSRbZnQYal1hS1L9uH94PFAFrB/70lEwTHY
/4fS5jfQt5CRieMv9WlnLRibgUR9BZstB7s/0lGU3nSMVz3kFte3wi+3xV6V19pH
WRWq8RR5lz7oY5etX9e0Pss1QiOpIsoSXglsCfX8dMNBoalETtlb6pxEeAK+0vxB
0UuBAdOR7PvCPmnEHEmY399jebZVfEHa04mNl6dVS9bGkar2vWOQZ5abryVcR8Kk
ZEyUcrOgKRUMdSaHtlRVSiuXBPFfkNpymXDfAVWW5Xqy+oC+44hvaV+aQZEZU6Y=
=LfgB
-----END PGP SIGNATURE-----