Open Stack

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.

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.

Michael
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/user-committee/attachments/20160801/3e687028/attachment.html>