<div dir="ltr"><div>As someone who contributes a significant number of diagrams to OpenStack documentation [1], I think I can provide some insight from a different (non-developer?) perspective. Primarily, we should consider the information that a diagram conveys and the audience that references it. A picture is worth a thousand words, so if you want to draw something, you might as well do it right.<br></div><div><br></div><div>Documentation that developers primarily reference (and maintain) probably benefits from the path of least resistance. In other words, not learning a new application or adhering to conventions such as fonts, color schemes, etc. If a text-type diagram can convey the information to other developers without becoming difficult to interpret or maintain, use it.</div><div><br></div><div>However, we should take a different approach for documentation that anyone other than developers might reference. After all, documentation plays a significant role in first impressions and text-type diagrams don't convey the "professional, commercially viable product" vibe to people who make decisions about adopting and implementing OpenStack. Therefore, such documentation benefits from image-type diagrams that adhere to conventions.</div><div><br></div><div>When in doubt, ask the documentation team. Most of us don't specialize in the development of any particular service and can therefore provide an "outside" opinion about the format, content, and potential audience of a diagram. Furthermore, we don't mind collaborating with developers to draw diagrams in any format or simply convert existing text-type diagrams to image-type diagrams.</div><div><br></div><div>Matt</div><div><br></div><div>[1] <a href="https://github.com/openstack/openstack-manuals/tree/master/doc/networking-guide/source/figures">https://github.com/openstack/openstack-manuals/tree/master/doc/networking-guide/source/figures</a></div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Fri, May 15, 2015 at 8:33 PM, Joe Gordon <span dir="ltr"><<a href="mailto:joe.gordon0@gmail.com" target="_blank">joe.gordon0@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote"><div><div class="h5">On Fri, May 15, 2015 at 2:27 PM, Joe Gordon <span dir="ltr"><<a href="mailto:joe.gordon0@gmail.com" target="_blank">joe.gordon0@gmail.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 dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote"><div><div>On Thu, May 14, 2015 at 3:52 AM, John Garbutt <span dir="ltr"><<a href="mailto:john@johngarbutt.com" target="_blank">john@johngarbutt.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"><span>On 12 May 2015 at 20:33, Sean Dague <<a href="mailto:sean@dague.net" target="_blank">sean@dague.net</a>> wrote:<br>
> On 05/12/2015 01:12 PM, Jeremy Stanley wrote:<br>
>> On 2015-05-12 10:04:11 -0700 (-0700), Clint Byrum wrote:<br>
>>> It's a nice up side. However, as others have pointed out, it's only<br>
>>> capable of displaying the most basic pieces of the architecture.<br>
>>><br>
>>> For higher level views with more components, I don't think ASCII art<br>
>>> can provide enough bandwidth to help as much as a vector diagram.<br>
>><br>
>> Of course, simply a reminder that just because you have one or two<br>
>> complex diagram callouts in a document doesn't mean it's necessary<br>
>> to also go back and replace your simpler ASCII art diagrams with<br>
>> unintelligible (without rendering) SVG or Postscript or whatever.<br>
>> Doing so pointlessly alienates at least some fraction of readers.<br>
><br>
> Sure, it's all about trade offs.<br>
><br>
> But I believe that statement implicitly assumes that ascii art diagrams<br>
> do not alienate some fraction of readers. And I think that's a bad<br>
> assumption.<br>
><br>
> If we all feel alienated every time anyone does anything that's not<br>
> exactly the way we would have done it, it's time to give up and pack it<br>
> in. :) This thread specifically mentioned source based image formats<br>
> that were internationally adopted open standards (w3c SVG, ISO ODG) that<br>
> have free software editors that exist in Windows, Mac, and Linux<br>
> (Inkscape and Open/LibreOffice).<br>
<br>
</span>Some great points make here.<br>
<br>
Lets try decide something, and move forward here.<br>
<br>
Key requirements seem to be:<br>
* we need something that gives us readable diagrams<br>
* if its not easy to edit, it will go stale<br>
* ideally needs to be source based, so it lives happily inside git<br>
* needs to integrate into our sphinx pipeline<br>
* ideally have an opensource editor for that format (import and<br>
export), for most platforms<br>
<br>
ascii art fails on many of these, but its always a trade off.<br>
<br>
Possible way forward:<br>
* lets avoid merging large hard to edit bitmap style images<br>
* nova-core reviewers can apply their judgement on merging source based formats<br>
* however it *must* render correctly in the generated html (see result<br>
of docs CI job)<br>
<br>
Trying out SVG, and possibly blockdiag, seem like the front runners.<br>
I don't think we will get consensus without trying them, so lets do that.<br>
<br>
Will that approach work?<br>
<br></blockquote><div><br></div></div></div><div>Sounds like a great plan.</div></div></div></div></blockquote><div><br></div><div><br></div><div><br></div></div></div><div>After further investigation in blockdiag, is useless for moderately complex diagrams. </div><div><br></div><div>Here is my attempt at graphing nova [0], but due to a blockdiag bug from 2013, [1] it is impossible to clearly read. For example, in the diagram there is not supposed to be any arrow between the conductor and cinder/glance/neutron. I looked into dia, and while it has plenty of diagram shapes it doesn't have a good template for software architecture, but maybe there is a way to make dia work. And that just  leaves SVG graphics,  after spending an hour or two  playing around with Inkscape and it looks promising (although the learning curve is pretty steep). Here is my first attempt in Inkscape [2].</div><div><br></div><div><br></div><div>[0] <a href="http://interactive.blockdiag.com/?compression=deflate&src=eJx9UMtOAzEMvOcrrL0vPwCtVHYryoG2EvSEOHiTtI0axavEFQK0_47dB1oOkEuSmbE9ni6SPbiAO_gyAJviM7yWPfYeJlChZcrV2-2VqafQxOAT62u2fhwTC8rhk9KIkWOMfuBOC0NyPtdLf-RMqX6ImKwXWbN6Wm9e5v9ppNcu07EXi_puVsv2LL-U6jAd8wsSTByJV-QgtibQU-aMgcft4G-RcBE7HzWH9h7QWl9KpaMKf0SNxxGzdyfkElgMSVcCS5GyFnYR7aESxCFjh8WPwt1Gerd7zHxzJc9J_2wiW8r93Czm7cnOYAZjhm9d4H0M" target="_blank">http://interactive.blockdiag.com/?compression=deflate&src=eJx9UMtOAzEMvOcrrL0vPwCtVHYryoG2EvSEOHiTtI0axavEFQK0_47dB1oOkEuSmbE9ni6SPbiAO_gyAJviM7yWPfYeJlChZcrV2-2VqafQxOAT62u2fhwTC8rhk9KIkWOMfuBOC0NyPtdLf-RMqX6ImKwXWbN6Wm9e5v9ppNcu07EXi_puVsv2LL-U6jAd8wsSTByJV-QgtibQU-aMgcft4G-RcBE7HzWH9h7QWl9KpaMKf0SNxxGzdyfkElgMSVcCS5GyFnYR7aESxCFjh8WPwt1Gerd7zHxzJc9J_2wiW8r93Czm7cnOYAZjhm9d4H0M</a></div><div>[1] <a href="https://bitbucket.org/blockdiag/blockdiag/issue/45/arrows-collisions" target="_blank">https://bitbucket.org/blockdiag/blockdiag/issue/45/arrows-collisions</a><br></div><div>[2] <a href="https://i.imgur.com/TXwsRoB.png" target="_blank">https://i.imgur.com/TXwsRoB.png</a></div><span class=""><div><br></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 dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><span><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">
Thanks,<br>
John<br>
<div><div><br>
__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</div></div></blockquote></span></div><br></div></div>
</blockquote></span></div><br></div></div>
<br>__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br></blockquote></div><br></div>