Open Stack

Hi all,
We had an informal video meet-n-greet yesterday and I wanted to send out
notes to summarize and let everyone know what's up if you couldn't attend.

Introductions: we have a new core team, and we wanted to put faces with
names while reviewing. Each of us talked about a focus area. This is a
small combined group of writers, developers, and API working group members.
https://review.openstack.org/#/admin/groups/1240,members

We need to create build jobs that copy the files through FTP to
developer.openstack.org/draft. Russell and Anne can collaborate on those
patches.

The source file formats are: Swagger JSON, which contains embedded
markdown, and RST files for introductory or definition/conceptual material.

We recognize the current UI is not ideal due to being long lists. Also some
APIs are more complex with more calls than others. Karen and Russell are
working on ideas for the front-end, but we can publish to
developer.openstack.org/draft in the meantime.

Anne has emailed half of the people on the API liaisons list at
http://specs.openstack.org/openstack/api-wg/liaisons.html and will email
the rest today (with any luck).

Focus area for teams are to test fairy-slipper's output, write tutorial
content from within their own repos (using nova jobs as a pattern), and
generally pay attention to what's new on developer.openstack.org.

Anne will import all existing Issues from the old fairy-slipper repo to
Launchpad at https://bugs.launchpad.net/openstack-doc-tools.

Top priorities:
1. Get build jobs so that teams can start poking at and improving the
output.
2. Keep reviews going on validated Swagger files, improve Swagger output to
compare completeness to developer.openstack.org/api-ref.html.
3. Focusing first on the Images v2.n API output, can we get an end-to-end
WADL conversion to Swagger that is tested and confirmed complete? Then move
to next API that is also not-as-complex as Compute or Identity, such as
Block Storage or Object Storage.
4. Focus first on the JSON for Swagger, then on validated JSON schema for
responses. We sense that what we have in the WADL is as good as it gets as
far as "what is truth."
5. Improving the UI for the JSON/RST output, finding ways to let readers
browse through narratives.

Not prioritizing yet:
1. Automatically scraping source code to generate docs.

It was great to see everyone! Feel free to add any additional info and
let's keep working on that to-do list.

Anne
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160115/5af657c6/attachment.html>