<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Mon, Aug 1, 2016 at 5:03 PM, Anne Gentle <span dir="ltr"><<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex"><div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote"><span class="">On Mon, Aug 1, 2016 at 1:57 PM, Michael Krotscheck <span dir="ltr"><<a href="mailto:krotscheck@gmail.com" target="_blank">krotscheck@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex"><div dir="ltr">Hello everyone!<div><br></div><div>TL/DR: I don't think the requirements, at their core, for a FirstApp document need to be changed. If we had additional bandwidth, we could restructure it to be more audience-targeted. If anything, I'd prefer it if we do not add sections for additional services without consulting with the experts on the documentation team.</div><div><br></div><div>Some relevant links:</div><div>Original Blog post: <a href="http://www.openstack.org/blog/2015/07/writing-your-first-openstack-application/" style="line-height:1.5" target="_blank">http://www.openstack.org/blog/2015/07/writing-your-first-openstack-application/</a></div><div>Current FirstApp Guide for Libcloud: <a href="http://developer.openstack.org/firstapp-libcloud/getting_started.html" target="_blank">http://developer.openstack.org/firstapp-libcloud/getting_started.html</a></div><div>How to write Documentation: <a href="https://jacobian.org/writing/great-documentation/" style="line-height:1.5" target="_blank">https://jacobian.org/writing/great-documentation/</a><br></div><div><br></div><div>=================</div><div><br></div><div>A couple of weeks ago Marcela asked the team whether the original framework sections for a FirstApp are out of date, and should be updated. Well, it turned out that the original doc was a skunkworks effort (which I didn't know), and very narrowly focused at libcloud</div></div></blockquote><div><br></div></span><div>Interesting, from where did this perception originate? What does skunkworks mean in this context?</div><span class=""><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div>.</div><div><br></div><div>I've also reached back into my archives and pulled up an amazing series of articles that talk about technical documentation. In particular, I will be referencing this article on What to Write (<a href="https://jacobian.org/writing/what-to-write/" target="_blank">https://jacobian.org/writing/what-to-write/</a>) with the remaining articles available at the link I've included above.</div><div><br></div><div>I feel that the libcloud guide attempts to hit the "Tutorial" segment of the article I linked, yet suffers a bit from the size of OpenStack. It's really not feasible to cram a getting started tutorial for a project this size into 30 minutes, but the libcloud guide gets very close.</div><div><br></div><div>In the absence of additional resources, I don't think we need to change the requirements (Keystone, Nova, Neutron, Glance, Cinder, Swift, Heat) at all. Should we get more resources, I would like to engage with the Documentation team and ask them for their professional advice on how to restructure the FirstApp guides to better meet the needs of a newcomer to OpenStack.</div></div></blockquote><div><br></div></span><div>I can help you recruit. :) Would like more info on this perception first so I can match the needs well.</div></div></div></div></blockquote><div><br></div><div>Hi again all, <br>I got to talk to Michael online and learned that skunkworks means "just try doing something that works" - to him, originating from Lockheed Martin's Advanced Development Programs. My questioning stemmed from a concern about a perception of being experimental and non-blessed, which isn't the case here. </div><div><br></div><div>To paint a picture of what we want for content on <a href="http://developer.openstack.org">developer.openstack.org</a>, envision a developer who works in any language, at a company that put an OpenStack cloud in place, who needs to get stuff working on that cloud, and doesn't have all the insider language that OpenStack contributors have picked up over the years. Heat? Keystone? Not in their vocabulary. FirstApp does fit this vision.</div><div><br></div><div>Marcela, are you still interested in redesigning the <a href="http://developer.openstack.org">developer.openstack.org</a> landing page? Let us know so we can plan towards requirements freeze on the Sphinx theme, which is August 29. </div><div><br></div><div>In related news, we are getting closer to having the API reference information usable in a sidebar navigation this month. Also of interest is that there are 27 REST API services in the big tent. Check out the newest projects.yaml file [1] that now identifies a docs: api: URL for projects that provide a user-facing REST API.</div><div><br></div><div>Thanks Michael and all. Let's keep working on incremental improvements to this information.</div><div><br></div><div>Anne</div><div><br></div><div>1. <a href="http://git.openstack.org/cgit/openstack/governance/plain/reference/projects.yaml">http://git.openstack.org/cgit/openstack/governance/plain/reference/projects.yaml</a></div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><br></div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex"><div dir="ltr"><span><font color="#888888"><div><br></div><div>Michael</div><div><br></div><div><br></div></font></span></div>
<br>_______________________________________________<br>
User-committee mailing list<br>
<a href="mailto:User-committee@lists.openstack.org" target="_blank">User-committee@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/user-committee" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/user-committee</a><br>
<br></blockquote></div><span class=""><font color="#888888"><br><br clear="all"><div><br></div>-- <br><div data-smartmail="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div>Anne Gentle</div><div><a href="http://www.justwriteclick.com" style="font-size:12.8px" target="_blank">www.justwriteclick.com</a><br></div></div></div></div></div>
</font></span></div></div>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div>Anne Gentle</div><div><a href="http://www.justwriteclick.com" style="font-size:12.8px" target="_blank">www.justwriteclick.com</a><br></div></div></div></div></div>
</div></div>