<div dir="ltr">Hi Lincoln,<div><br></div><div>Great questions, more below.</div><div class="gmail_extra"><br><br><div class="gmail_quote">On Fri, Nov 15, 2013 at 9:22 PM, Thomas, Lincoln (HP Storage R&D) <span dir="ltr"><<a href="mailto:Lincoln.Thomas@hp.com" target="_blank">Lincoln.Thomas@hp.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div lang="EN-US" link="blue" vlink="purple">
<div>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif">Hi Doc folks, AnneG & co.,<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif">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.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif">We have a new Wiki page
<a href="https://wiki.openstack.org/wiki/MetadataSearch" target="_blank">https://wiki.openstack.org/wiki/MetadataSearch</a> where I’ve posted a PDF generated from an MS Word doc that I wrote, describing a proposed API.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif">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,</span><span style="font-size:10pt;font-family:Georgia,serif">
33 pages of dense text with lots of tables and formatting. <u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif">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.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif"><u></u> </span></p></div></div></blockquote><div><br></div><div>Our wiki format is mediawiki. I googled for "Word file to mediawiki" and found these instructions. </div>
<div><br></div><div><p style="margin:0.4em 0px 0.5em;line-height:19.1875px;color:rgb(0,0,0);font-family:sans-serif;font-size:13px">Microsoft released an add-in that allows you to save your Windows Microsoft Office Word 2007 or above documents straight into MediaWiki.</p>
<ol style="line-height:19.1875px;margin:0.3em 0px 0px 3.2em;padding:0px;color:rgb(0,0,0);font-family:sans-serif;font-size:13px"><li style="margin-bottom:0.1em">Download the "<a rel="nofollow" class="" href="http://www.microsoft.com/downloads/en/details.aspx?FamilyID=8e519637-afb0-4134-a91f-7b0ebea8d933" style="text-decoration:none;color:rgb(102,51,102)">Microsoft Office Word Add-in For MediaWiki</a>" (<a href="http://www.microsoft.com/en-us/download/details.aspx?id=12298">http://www.microsoft.com/en-us/download/details.aspx?id=12298</a>) from Microsoft Download Center, and install it.</li>
<li style="margin-bottom:0.1em">Save the document as "MediaWiki (*.txt)" file type.</li><li style="margin-bottom:0.1em">Copy the text from the (*.txt) file into your Wiki page</li></ol></div><div> </div><div>As for the number of pages you'd output, I'm not sure. </div>
<div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div lang="EN-US" link="blue" vlink="purple">
<div><p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif">Or would you suggest a better form for the doc that could be posted and would allow collaborative updating? (Please, not Etherpad! ;-)<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif">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.</span></p>
</div></div></blockquote><div><br></div><div><br></div><div>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. </div>
<div><br></div><div>The document you reference, <a href="http://docs.openstack.org/api/openstack-object-storage/1.0">http://docs.openstack.org/api/openstack-object-storage/1.0</a>, is built from the object-api repository, <a href="https://github.com/openstack/object-api">https://github.com/openstack/object-api</a>. 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. </div>
<div><br></div><div>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 <a href="http://api.openstack.org/api-ref.html">http://api.openstack.org/api-ref.html</a>. It's also how Compute API extensions are documented. Take a look at <a href="http://justwriteclick.com/2013/04/14/how-its-made-the-openstack-api-reference-page/">http://justwriteclick.com/2013/04/14/how-its-made-the-openstack-api-reference-page/</a> for details.<br>
</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div lang="EN-US" link="blue" vlink="purple">
<div><p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif"><u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif">Are there other cases of APIs/specs in OpenStack being created/updated internally before becoming finally published, and the formats they used during development?</span></p>
</div></div></blockquote><div><br></div><div>Absolutely. Wiki is common for the reasons you note - collaboration and comments - during the "spec" stage.</div><div><br></div><div>Thanks,</div><div>Anne</div><div>
</div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div lang="EN-US" link="blue" vlink="purple"><div>
<p class="MsoNormal">
<span style="font-size:10pt;font-family:Georgia,serif"><u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif">Thanks in advance,<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif">Lincoln Thomas<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif">HP Storage R&D<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif"><a href="mailto:Lincoln.thomas@hp.com" target="_blank">Lincoln.thomas@hp.com</a><u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif"><u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:10pt;font-family:Georgia,serif"><u></u> <u></u></span></p>
</div>
</div>
<br>_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br></blockquote></div><br><br clear="all"><div><br></div>-- <br>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>
</div></div>