<div dir="ltr">Hello Lana!<div><br></div><div>Thank you for your prompt reply--  I found it extremely helpful!  Comments inline:</div><div class="gmail_extra"><br><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div class="h5"><br>
> So in the intervening days I've been going through the openstack-manuals,<br>
> openstack-doc-tools, and other repositories, trying to figure out where I<br>
> make my edits. I found both the CLI and API reference in the<br>
> openstack-manuals repository... but when I went to edit these files, I<br>
> noticed that there's a comment at the top stating they are auto-generated<br>
> and shouldn't be edited? It seemed odd to me that the results of something<br>
> auto-generated should be checked into a git repository instead of the<br>
> configuration which creates the auto-generated output... but it's not my<br>
> project, right?<br>
<br>
</div></div>Believe me, we know. At the moment, this is the best we can do with what we have to work with.<br></blockquote><div><br></div><div>Yep! I get it.</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">
> Anyway, so then I went to try to figure out how I get this auto-generated<br>
> output updated, and haven't found much (ha!) documented on the process...<br>
> when I sought help from Sam-I-Am, I was told that these essentially get<br>
> generated once per release by "somebody." So...  I'm done, right?<br>
<br>
</span>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.<br>
<span class=""><br></span></blockquote><div><br></div><div>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)?</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">
> Well... I'm not so sure. Yes, if the CLI and API documentation gets<br>
> auto-generated from the right sources, we should be good to go on that<br>
> front, but how can I be sure the automated process is pulling this<br>
> information from the right place? Shouldn't there be some kind of<br>
> continuous integration or jenkins check which tests this that I can look<br>
> at? (And if such a thing exists, how am I supposed to find out about it?)<br>
><br>
> Also, the new feature I've added is somewhat involved, and it could<br>
> probably use another document describing its intended use beyond the CLI /<br>
> API ref. Heck, we already created on in the OpenStack wiki... but I'm also<br>
> being told that we're trying to not rely on the wiki as much, per se, and<br>
> that anything in the wiki really ought to be moved into the "official"<br>
> documentation canon.<br>
<br>
</span>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 <a href="http://docs.openstack.org/developer/[yourproject]" rel="noreferrer" target="_blank">http://docs.openstack.org/developer/[yourproject]</a> and are considered official OpenStack documentation.<br>
<br>
If you want it added to the broader OpenStack documentation (the top level on the <a href="http://docs.openstack.org" rel="noreferrer" target="_blank">docs.openstack.org</a>), 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.<br>
<span class=""><br></span></blockquote><div><br></div><div>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.</div><div><br></div><div>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!</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">
><br>
> So.... I'm at a loss. I'm a big fan of documentation as a communication<br>
> tool, and I'm an experienced OpenStack developer, but when I look in the<br>
> manual for how to contribute to the OpenStack documentation, I find a guide<br>
> that wants to walk me through setting up gerrit... and very little targeted<br>
> toward someone who already knows that, but just needs to know the actual<br>
> process for updating the manual (and which part of the manual should be<br>
> updated).<br>
<br>
</span>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.<br></blockquote><div><br></div><div>...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...)</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class=""><br>
> When I went back to Sam-I-Am about this, this spawned a much larger<br>
> discussion and he suggested I bring this up on the mailing list because<br>
> there might be some "big picture" issues at play that should get a larger<br>
> discussion. So... here I am.<br>
><br>
> Here's what I think the problem is:<br>
><br>
> * We want developers to document the features they add or modify<br>
> * We want developers to provide good user, operator, etc. documentation<br>
> that actual users, operators, etc. can use to understand and use the<br>
> software we're writing.<br>
> * We even go so far as to say that a feature is not complete unless it has<br>
> this documentation (which I agree with)<br>
> * With a rather small openstack-docs contributor team, we want to automate<br>
> as much as possible, and rely on the docs team to *edit* documentation<br>
> written by developers instead of writing the docs themselves (which is more<br>
> time consuming for the docs team to do, and may miss important things only<br>
> the developers know about.)<br>
<br>
</span>I agree with all of your points here.<br>
<span class=""><br>
><br>
> But:<br>
><br>
> * We don't actually provide much help to the developers to know how to do<br>
> this. We have plenty for people who are new to OpenStack to get started<br>
> with gerrit--  but there doesn't seem to be much practical help on where to<br>
> get started, as an experienced contributor to other projects, on the actual<br>
> task of updating the manual.<br>
<br>
</span>As I said earlier, it's no different to contributing to other projects, so you already have the requisite skills.<br>
<span class=""><br>
><br>
> And I would wager:<br>
><br>
> * We don't seem to have many automated tools that tie into the jenkins gate<br>
> checks to make sure that new features are properly documented.<br>
> * We need something better than the 'APIImpact' and 'DocImpact' flags you<br>
> can add to a commit message which generate docs project bug reports These<br>
> are post-hoc back-filling at best, and as I understand it, often mean that<br>
> some poor schmuck on the docs team will probably be the one who ends up<br>
> writing the docs for the feature the developer added, probably without the<br>
> developer's help.<br>
<br>
</span>I also agree with these points. We've recently overhauled the DocImpact flag to try and correct some of this behaviour.<br>
<span class=""><br>
><br>
> Please understand: I know that big strides have been made in the right<br>
> direction here recently, and I know that the docs team is both small and<br>
> under-appreciated. For example, the move from XML-based documentation to<br>
> .rst based documentation is a huge step in a direction that will prevent<br>
> most developers from wanting to gouge their own eyes out anymore when it<br>
> comes to writing documentation (though in my searching over the last few<br>
> days I did find one api reference repository where it looked like people<br>
> are actually editing raw XML and submitting this through the gerrit review<br>
> process... please tell me this is not actually still the state of affairs!)<br>
<br>
</span>Thanks. It was a lot of hard work, and we're not quite there yet. API docs are in the process of some major changes, though, so please watch this space.<br></blockquote><div><br></div><div>Ok, good to know!</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<span class=""><br>
><br>
> Also, I certainly don't blame the docs team for the history of how we got<br>
> to where we are today. I'm pretty sure everyone on that (and most) projects<br>
> is truly here to make the OpenStack world a better place and is working<br>
> hard to make that happen. Nobody is trying to burn the house down.<br>
><br>
> But I think there are some flames that need extinguishing. I'm writing this<br>
> e-mail because I think we've got some additional steps that need to be<br>
> taken to actually help experienced openstack contributors know *how* they<br>
> go about updating the openstack docs. It's not that we aren't willing to<br>
> write documentation (well, I don't think most are unwilling), it's that the<br>
> process for doing this seems extremely obfuscated.<br>
<br>
</span>I'm pleased to say that we have many developers in the OpenStack community who are very dedicated to contributing great documentation, and committed to ensuring the docs we have are also very high quality. Just submit a patch in exactly the same way as you would for any other project.</blockquote><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<span class=""><br>
><br>
> Ideally, I would like to see a practical and relatively short how-to guide<br>
> along the lines of: "The shiny new feature you added to your OpenStack<br>
> project has merged. Congratulations! Here's how you update the manual..."<br>
> This should be written by someone already very familiar with the OpenStack<br>
> documentation system. This practical guide would provide answers for:<br>
><br>
> * How to actually ensure that API / CLI documentation is updated (if it's<br>
> actually automated, and what the process for that is so that others can<br>
> check.)<br>
> * Criteria to know when more documentation is required than just API / CLI<br>
> reference updates<br>
> * Where to put this more extensive documentation.<br>
> * Other non-intuitive information you should know (eg. what image format<br>
> diagrams should be in, and best practices for uploading them, plus style<br>
> guides for the images)<br>
<br>
</span>All of this is documented in the Infra manual, with a few docs-specific things (docs repos, writing style, etc) in our Contributor Guide: <a href="http://docs.openstack.org/contributor-guide/index.html" rel="noreferrer" target="_blank">http://docs.openstack.org/contributor-guide/index.html</a><br>
<br>
If you feel there's something specific missing, please raise a bug in our queue, or propose a patch to the Contributor Guide.<br></blockquote><div><br></div><div>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.</div><div><br></div><div>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...</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">
> Even more ideally, I would like to see a practical how-to guide along the<br>
> lines of: "So you've started a new OpenStack project. Here's how to make<br>
> sure it plays nice with the documentation system..." This would provide<br>
> answers for:<br>
><br>
> * How to set up automated tests to ensure documentation meets<br>
> machine-discernable standards for the openstack manual (eg. pep8 for docs<br>
> with specific style-enforcement included)<br>
<br>
</span>I've been a technical writer in a professional capacity for a very long time, and I've not yet seen anyone even attempt to enforce style automatically. English is tricky. That said, we do already run a series of Jenkins jobs to ensure books build, and links resolve, etc.<br></blockquote><div><br></div><div>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.</div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">
> * How to set up automated tests to ensure that documentation is either<br>
> imported from your project to the OpenStack manual (less ideal, I know--<br>
> coders are coders and not writers for a reason), or that there are hooks<br>
> from the openstack manual into your project which flag and potentially<br>
> block merges of insufficiently-documented changes (ie. something better<br>
> than adding 'APIImpact' and 'DocImpact' to your commit message and hoping<br>
> somebody comes along and documents it at some point).<br>
<br>
</span>This was part of the concerns we had around DocImpact that forced the recent changes, and we eventually determined that really it needs human (not automated) intervention to decide what 'complete' means in the sense of documentation.</blockquote><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>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.</div><div> </div><div>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. :) </div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">
> * Best practices for things like where to put the documentation, how and<br>
> when to require release notes, documentation templates with the proper<br>
> style, where to put sample config files so they get automatically slurped<br>
> into the openstack manual, etc.<br>
> * How to know if certain types of documentation are inappropriate for the<br>
> openstack manual, and best practices on where to put this, if not in the<br>
> manual.<br>
<br>
</span>These are very subjective things, and you really need someone skilled in the art of Information Architecture to determine this. It's another reason why we ask people to wait while the docs team triage their bug. If you could work out how to wrap rules around IA, you'd put a lot of us out of work and, incidentally, render my university degree pointless. Information Architecture, translation, technical writing and associated tasks are all very much more an art than a science.<br>
<br>
But, on the upside, you know we have a mailing list now, and we're always willing to answer these kinds of questions for you. The thing about writers is we genuinely love being asked about writing. Try us ;)<br></blockquote><div><br></div><div>See, this is one of the things I think we could improve upon:</div><div><br></div><div>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."</div><div><br></div><div>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).</div><div><br></div><div>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.</div><div><br></div><div>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."</div><div><br></div><div>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!</div><div><br></div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">
> I fully admit that it's possible the above may already exist scattered in<br>
> various places in the current documentation structure. However, I can tell<br>
> you from my experience in the several OpenStack projects I've contributed<br>
> to, that it is apparently not easily located or consumed because very few<br>
> of the experienced contributors I work with have any clue about much of the<br>
> above.<br>
<br>
</span>I'm very sad to hear this. Docs handled in the same way as code has been our guiding principle since Anne Gentle formed the openstack-manuals team. What else should we be doing to get this message out there?<br></blockquote><div><br></div><div>I agree that handling docs like code is a good thing. Maybe adding the "Doc-Change:" feature described above could aid in that. :)</div><div><br></div><div>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)?</div><div><br></div><div>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.)</div><div><br></div><div>Does that make sense?</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">
> Please also note that I am *NOT* volunteering to write the above documents<br>
> per se: The above docs need to be written by someone actually familiar with<br>
> the documentation system. But it will be effort well spent, because when<br>
> developers actually do start contributing documentation along with their<br>
> new code, you'll get to spend more time editing those documentation<br>
> contributions than writing them from scratch yourself. And everyone wins<br>
> then because the OpenStack documentation becomes more complete and sucks<br>
> less.<br>
<br>
</span>We greatly appreciate all the developers who contribute to docs. There are many already involved, but it's always wonderful to welcome more :)<br>
<span class=""><br>
><br>
> In any case, I am certainly willing to provide feedback on the above<br>
> suggested how-to guides, should someone decide to write them.<br>
><br>
> Thanks,<br>
> Stephen<br>
><br>
> P.S. I still have no idea how I go about updating the manual for the major<br>
> features that we added to neutron-lbaas and Octavia in this cycle.<br>
<br>
</span>Your automated content should be here: <a href="http://docs.openstack.org/liberty/config-reference/content/networking-plugin-lbaas.html" rel="noreferrer" target="_blank">http://docs.openstack.org/liberty/config-reference/content/networking-plugin-lbaas.html</a> Please raise a bug against openstack-manuals (<a href="https://launchpad.net/openstack-manuals" rel="noreferrer" target="_blank">https://launchpad.net/openstack-manuals</a>) if that is not the case.<br>
<br></blockquote><div><br></div><div>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.)</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Octavia is documented here: <a href="http://docs.openstack.org/developer/octavia/" rel="noreferrer" target="_blank">http://docs.openstack.org/developer/octavia/</a> If you have content to add, propose a patch to <a href="http://git.openstack.org/cgit/openstack/octavia" rel="noreferrer" target="_blank">http://git.openstack.org/cgit/openstack/octavia</a><br>
<br></blockquote><div><br></div><div>Yep-- contributed a good portion of that myself already, actually. :) (Didn't know that was "kosher.")</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
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.<br></blockquote><div><br></div><div>Cool beans! I'm "sbalukoff" on IRC and can usually be raised in the #openstack-lbaas channel.</div><div><br></div><div>Thanks,</div><div>Stephen</div><div> </div></div><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div><span></span><div>Stephen Balukoff</div><div>Principal Technologist</div><div>Blue Box, An IBM Company</div><div><a href="http://www.blueboxcloud.com" target="_blank">www.blueboxcloud.com</a></div><div><a href="mailto:sbalukoff@blueboxcloud.com" target="_blank">sbalukoff@blueboxcloud.com</a></div><div>206-607-0660 x807</div></div></div></div></div></div>
</div></div>