Open Stack

Hi Lincoln,

Great questions, more below.


On Fri, Nov 15, 2013 at 9:22 PM, Thomas, Lincoln (HP Storage R&D) <
Lincoln.Thomas at hp.com> wrote:

>  Hi Doc folks, AnneG & co.,
>
>
>
> I’m looking for your doc experience here to help us with a
> developer-facing doc. It may eventually become documented externally as an
> extension to the existing Swift API, so it may end up in your lap in 4-12
> months anyway.
>
>
>
> We have a new Wiki page https://wiki.openstack.org/wiki/MetadataSearchwhere I’ve posted a PDF generated from an MS Word doc that I wrote,
> describing a proposed API.
>
>
>
> We’d like to convert this into Wiki form and put it on the page directly,
> so we can update it frequently and keep the history of changes. The current
> PDF is big, 33 pages of dense text with lots of tables and formatting.
>
>
>
> How would you suggest we convert that into OpenStack’s Wiki format? Onto
> that one page, or a page with child Wiki pages? We’d also like to collect
> comments/feedback from the community on that Wiki page(s). A handful of us
> leads on this topic would be the only ones editing it, typically.
>
>
>

Our wiki format is mediawiki. I googled for "Word file to mediawiki" and
found these instructions.

Microsoft released an add-in that allows you to save your Windows Microsoft
Office Word 2007 or above documents straight into MediaWiki.

   1. Download the "Microsoft Office Word Add-in For
MediaWiki<http://www.microsoft.com/downloads/en/details.aspx?FamilyID=8e519637-afb0-4134-a91f-7b0ebea8d933>"
   (http://www.microsoft.com/en-us/download/details.aspx?id=12298) from
   Microsoft Download Center, and install it.
   2. Save the document as "MediaWiki (*.txt)" file type.
   3. Copy the text from the (*.txt) file into your Wiki page


As for the number of pages you'd output, I'm not sure.



> Or would you suggest a better form for the doc that could be posted and
> would allow collaborative updating? (Please, not Etherpad! ;-)
>
>
>
> Like I said, it may end up being a published API, so something that you
> can eventually convert to your formats/templates (HTML/PDF) would be good
> too.
>


One note of who "you" is -- we have very few resources working on API docs.
Diane Fleming is the main API doc maintainer, but only for end-users, not
for developers. Your document is in a "developer" audience stage in my
mind. For end users, our API doc format is DocBook and WADL. For developers
writing to the API spec, you can use RST, markdown, or wiki. When you get
to that point, we can guide you for what goes where -- reference
information or how-to information.

The document you reference,
http://docs.openstack.org/api/openstack-object-storage/1.0, is built from
the object-api repository, https://github.com/openstack/object-api. However
we decided at the Summit to move those "specs" into the project repository
itself during the icehouse release. Swift has the most un-spec-like
document of the 10 specs, but still, that's the direction we're moving in.

I've read the document you reference and it seems like it would be easy to
understand with a WADL as well. WADL is what we use to build the API
Reference page at http://api.openstack.org/api-ref.html. It's also how
Compute API extensions are documented. Take a look at
http://justwriteclick.com/2013/04/14/how-its-made-the-openstack-api-reference-page/for
details.


>
>
> Are there other cases of APIs/specs in OpenStack being created/updated
> internally before becoming finally published, and the formats they used
> during development?
>

Absolutely. Wiki is common for the reasons you note - collaboration and
comments - during the "spec" stage.

Thanks,
Anne


>
>
> Thanks in advance,
>
> Lincoln Thomas
>
> HP Storage R&D
>
> Lincoln.thomas at hp.com
>
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>


-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20131118/ff1d9151/attachment.html>