<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Fri, May 8, 2015 at 12:26 PM, Monty Taylor <span dir="ltr"><<a href="mailto:mordred@inaugust.com" target="_blank">mordred@inaugust.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div class=""><div class="h5">On 05/07/2015 12:04 PM, Anne Gentle wrote:<br>
> On Thu, May 7, 2015 at 9:12 AM, Ildikó Váncsa <<a href="mailto:ildiko.vancsa@ericsson.com">ildiko.vancsa@ericsson.com</a>><br>
> wrote:<br>
><br>
>>  Hi All,<br>
>><br>
>><br>
>><br>
>> I missed the original thread with the registration to this list, so I will<br>
>> try to summarize my thoughts without history.<br>
>><br>
>><br>
>><br>
>> First of all, I support the idea of generating the API Reference from the<br>
>> source code as that is the most up to date source of information. On the<br>
>> other hand it makes much easier not just to create the exact document, but<br>
>> keep it up to date, which is unfortunately not true for some of the<br>
>> projects that have their API guide in OpenStack Manuals.<br>
>><br>
>><br>
>><br>
>> As for the format and placement, I think it can be an experimental process<br>
>> as it is described in the corresponding blueprint. As there are still<br>
>> projects, which have their API documentation in the project tree it shows<br>
>> that it is a viable solution too to put more responsibility on the project<br>
>> teams as opposed to leaving all on the documentation team, which has<br>
>> limited resources compared to the size of OpenStack at the moment.<br>
>><br>
>><br>
>><br>
>> As I mentioned the documentation, which lives together with the code, it<br>
>> raised a question for me. The API versioning is not always in line with the<br>
>> OpenStack releases neither with the changes on the API. As not every<br>
>> project uses micro versioning or any kind of markup, which shows the<br>
>> changes, it can mean that the v2 version of an API contains less endpoints<br>
>> in let’s Juno, than in Kilo. If we document and update the API Reference<br>
>> based only on API versions, then we miss to capture the difference between<br>
>> the functionality covered in the different OpenStack releases. In case of<br>
>> those projects, which maintains their documentation together with the code<br>
>> base this should not be an issue, as the documentation is frozen on the<br>
>> stable branches, when those are cut from master. What do you think about<br>
>> this aspect? Is there a plan to address this issue too?<br>
>><br>
><br>
> Great point Ildiko. I need to be clear in the spec that the intent is to<br>
> have a "Kilo" Dev Guide, a "Juno" Dev Guide, probably just maintaining 2<br>
> releases at a time (rather than the 3 that are security-supported). I think<br>
> it'll have to lag a release behind, so that Dev Guides are only available<br>
> for already-released services.<br>
><br>
> To keep the scope sane, I likely will start with Images v2.x API only. I'm<br>
> reaching out to that team to see if that's feasible.<br>
><br>
> So it's not about the projects microversioning each resource call<br>
> necessarily but about documenting "what can I do with a Juno-based cloud as<br>
> an app dev" -- and document ways to self-discover that also. In your case,<br>
> how would I know what calls are available in Juno, use stable branches? I<br>
> guess I point the autodoc tool at the stable branch. Hm, this might mean<br>
> some backported strings.<br>
<br>
</div></div>I support more guides for app developers ... however, I'd like to be the<br>
annoying person that points out that an app developer does not know or<br>
care if the OpenStack cloud they are interacting with is running Juno or<br>
not.<br>
<br>
I currently have credentials on 5 different public clouds. I do not know<br>
what version of OpenStack is running on them. I do not want to know. I<br>
certainly do not want to have to know.<br></blockquote><div><br></div><div>I absolutely agree that discoverability is part of this puzzle. </div><div><br></div><div>But in reading your response I can't help but think, where does upstream's responsibility stop and downstream's start? As in, even if I make great upstream dev guides, the devs still have to poke at the cloud they are consuming. </div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<span class=""><br>
> Each resource should have some indicator in the docs whether it's available<br>
> on Juno or Kilo, also. That's what's tougher for some APIs than others,<br>
> right?<br>
<br>
</span>The things an app developer needs to know are:<br>
<br>
- what version of the API is it in?<br>
- how to discover what version of the API the cloud in question supports<br>
- how to discover whether or not the cloud in question supports the feature<br>
<br></blockquote><div><br></div><div>Okay, so is it upstream's responsibility just to tell them the answers to these three questions, and that's it? The first question is fairly straightforward. The second is what I might say "not upstream doc's responsibility" though.</div><div><br></div><div>So that's why we really need to work on the service catalog and why putting versions in endpoints is a bad deal for end users.</div><div><br></div><div>And the third, why would an app dev look to upstream docs to answer that question? Wouldn't they look to their cloud provider? </div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
As an example, Image API v1 and v2 support PUT as a mechanism to upload<br>
images, but Rackspace cloud has it disabled as a deployment choice. I<br>
have no idea which version of glance they're running, but with the above<br>
information, I am able to use the Image API successfully.<br>
<div class=""><div class="h5"><br></div></div></blockquote><div><br></div><div>Right, and so Rackspace has a responsibility, sure. Does a Rackspace cloud user come to OpenStack docs? I know they do, but they do a comparison, which is still more time taken away from making a powerful app.<br></div><div><br></div><div>So I guess what I still want to know is, what should upstream provide? Is the first question's answer, "What version of an API is it in" sufficient? With microversions and off/on configured capabilities, the version value alone is not sufficient. </div><div><br></div><div>So I guess I come back to, each call in upstream doc needs to indicate somehow when it was added, and how to tell if it's in the cloud you're using. </div><div><br></div><div>This is starting to feel less like a docs solution is sufficient and more like a standard usability solution is required. To me, that points to project-embedded solutions and consistency across all OpenStack APIs. I'll update the spec accordingly.</div><div>Thanks,</div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div class=""><div class="h5">
> I really want to get the proof-of-concept robust enough to matter, so<br>
> thanks for bringing up the versioning implications.<br>
><br>
> Anne<br>
><br>
><br>
>><br>
>><br>
>> Best Regards,<br>
>><br>
>> Ildiko<br>
>><br>
>> _______________________________________________<br>
>> OpenStack-docs mailing list<br>
>> <a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br>
>> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
>><br>
>><br>
><br>
><br>
><br>
><br>
> _______________________________________________<br>
> OpenStack-docs mailing list<br>
> <a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
><br>
<br>
<br>
_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
</div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature">Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a></div>
</div></div>