Open Stack

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.

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.

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.

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.

Matt

[1]
https://github.com/openstack/openstack-manuals/tree/master/doc/networking-guide/source/figures


On Fri, May 15, 2015 at 8:33 PM, Joe Gordon <joe.gordon0 at gmail.com> wrote:

>
>
> On Fri, May 15, 2015 at 2:27 PM, Joe Gordon <joe.gordon0 at gmail.com> wrote:
>
>>
>>
>> On Thu, May 14, 2015 at 3:52 AM, John Garbutt <john at johngarbutt.com>
>> wrote:
>>
>>> On 12 May 2015 at 20:33, Sean Dague <sean at dague.net> wrote:
>>> > On 05/12/2015 01:12 PM, Jeremy Stanley wrote:
>>> >> On 2015-05-12 10:04:11 -0700 (-0700), Clint Byrum wrote:
>>> >>> It's a nice up side. However, as others have pointed out, it's only
>>> >>> capable of displaying the most basic pieces of the architecture.
>>> >>>
>>> >>> For higher level views with more components, I don't think ASCII art
>>> >>> can provide enough bandwidth to help as much as a vector diagram.
>>> >>
>>> >> Of course, simply a reminder that just because you have one or two
>>> >> complex diagram callouts in a document doesn't mean it's necessary
>>> >> to also go back and replace your simpler ASCII art diagrams with
>>> >> unintelligible (without rendering) SVG or Postscript or whatever.
>>> >> Doing so pointlessly alienates at least some fraction of readers.
>>> >
>>> > Sure, it's all about trade offs.
>>> >
>>> > But I believe that statement implicitly assumes that ascii art diagrams
>>> > do not alienate some fraction of readers. And I think that's a bad
>>> > assumption.
>>> >
>>> > If we all feel alienated every time anyone does anything that's not
>>> > exactly the way we would have done it, it's time to give up and pack it
>>> > in. :) This thread specifically mentioned source based image formats
>>> > that were internationally adopted open standards (w3c SVG, ISO ODG)
>>> that
>>> > have free software editors that exist in Windows, Mac, and Linux
>>> > (Inkscape and Open/LibreOffice).
>>>
>>> Some great points make here.
>>>
>>> Lets try decide something, and move forward here.
>>>
>>> Key requirements seem to be:
>>> * we need something that gives us readable diagrams
>>> * if its not easy to edit, it will go stale
>>> * ideally needs to be source based, so it lives happily inside git
>>> * needs to integrate into our sphinx pipeline
>>> * ideally have an opensource editor for that format (import and
>>> export), for most platforms
>>>
>>> ascii art fails on many of these, but its always a trade off.
>>>
>>> Possible way forward:
>>> * lets avoid merging large hard to edit bitmap style images
>>> * nova-core reviewers can apply their judgement on merging source based
>>> formats
>>> * however it *must* render correctly in the generated html (see result
>>> of docs CI job)
>>>
>>> Trying out SVG, and possibly blockdiag, seem like the front runners.
>>> I don't think we will get consensus without trying them, so lets do that.
>>>
>>> Will that approach work?
>>>
>>>
>> Sounds like a great plan.
>>
>
>
>
> After further investigation in blockdiag, is useless for moderately
> complex diagrams.
>
> 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].
>
>
> [0]
> http://interactive.blockdiag.com/?compression=deflate&src=eJx9UMtOAzEMvOcrrL0vPwCtVHYryoG2EvSEOHiTtI0axavEFQK0_47dB1oOkEuSmbE9ni6SPbiAO_gyAJviM7yWPfYeJlChZcrV2-2VqafQxOAT62u2fhwTC8rhk9KIkWOMfuBOC0NyPtdLf-RMqX6ImKwXWbN6Wm9e5v9ppNcu07EXi_puVsv2LL-U6jAd8wsSTByJV-QgtibQU-aMgcft4G-RcBE7HzWH9h7QWl9KpaMKf0SNxxGzdyfkElgMSVcCS5GyFnYR7aESxCFjh8WPwt1Gerd7zHxzJc9J_2wiW8r93Czm7cnOYAZjhm9d4H0M
> [1] https://bitbucket.org/blockdiag/blockdiag/issue/45/arrows-collisions
> [2] https://i.imgur.com/TXwsRoB.png
>
>
>>
>>> Thanks,
>>> John
>>>
>>>
>>> __________________________________________________________________________
>>> OpenStack Development Mailing List (not for usage questions)
>>> Unsubscribe:
>>> OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>>
>>
>>
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150516/ecafbc37/attachment.html>