Open Stack

On Mon, Aug 1, 2016 at 5:03 PM, Anne Gentle <annegentle at justwriteclick.com>
wrote:

>
>
> On Mon, Aug 1, 2016 at 1:57 PM, Michael Krotscheck <krotscheck at gmail.com>
> wrote:
>
>> Hello everyone!
>>
>> 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.
>>
>> Some relevant links:
>> Original Blog post:
>> http://www.openstack.org/blog/2015/07/writing-your-first-openstack-application/
>> Current FirstApp Guide for Libcloud:
>> http://developer.openstack.org/firstapp-libcloud/getting_started.html
>> How to write Documentation:
>> https://jacobian.org/writing/great-documentation/
>>
>> =================
>>
>> 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
>>
>
> Interesting, from where did this perception originate? What does
> skunkworks mean in this context?
>
>
>> .
>>
>> 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 (
>> https://jacobian.org/writing/what-to-write/) with the remaining articles
>> available at the link I've included above.
>>
>> 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.
>>
>> 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.
>>
>
> I can help you recruit. :) Would like more info on this perception first
> so I can match the needs well.
>

Hi again all,
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.

To paint a picture of what we want for content on developer.openstack.org,
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.

Marcela, are you still interested in redesigning the developer.openstack.org
landing page? Let us know so we can plan towards requirements freeze on the
Sphinx theme, which is August 29.

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.

Thanks Michael and all. Let's keep working on incremental improvements to
this information.

Anne

1.
http://git.openstack.org/cgit/openstack/governance/plain/reference/projects.yaml



>
> Anne
>
>
>>
>> Michael
>>
>>
>>
>> _______________________________________________
>> User-committee mailing list
>> User-committee at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/user-committee
>>
>>
>
>
> --
> Anne Gentle
> www.justwriteclick.com
>



-- 
Anne Gentle
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/user-committee/attachments/20160803/3e2421f0/attachment.html>