[OpenStack-docs] Diagram recommendations for Openstack Contributor Guides

Shaun O'Meara someara at mirantis.com
Fri May 13 19:08:30 UTC 2016


+1 to Nate.

On Fri, 13 May 2016 at 8:43 PM Nate Archer <Nate.Archer at rackspace.com>
wrote:

> Let me play devil’s advocate to Shaun’s advocate. :)
>
> While the contribution of a diagram becomes easier by allowing any
> contributor to use their own tool so as long as the contributor follows
> explicit guidelines, the act of reviewing/modifying a diagram to ensure it
> meets our standards becomes more difficult when we do not dictate or
> suggest a toolset. As Matt points out, we need to consider our review
> options.
>
> If we want a reviewer to be able to modify a diagram with ease, we must
> consider what toolsets are compatible with one another.
>
> Alternatively, if we chose not to consider toolsets, we should be explicit
> about what type of assets(shapes, stencils, or project symbols) a
> contributor can use. That way, a reviewer can reproduce the assets of a
> contributor’s diagram in the reviewer's own editor. However, it may take
> the reviewer more time and effort to modify the diagram.
>
> -Nate
>
> From: Matt Kassawara <mkassawara at gmail.com>
> Date: Friday, May 13, 2016 at 1:08 PM
> To: Shaun O'Meara <someara at mirantis.com>
> Cc: Rackspace Hosting <Nate.Archer at rackspace.com>, Christian Berendt <
> christian at berendt.io>, Olga Gusarenko <ogusarenko at mirantis.com>, Shaun
> OMeara <shaun at omeara.co.za>, "openstack-docs at lists.openstack.org" <
> openstack-docs at lists.openstack.org>, Darren Chan <
> darren.chan at RACKSPACE.COM>
> Subject: Re: Diagram recommendations for Openstack Contributor Guides
>
> YES! As long as your tool of choice creates diagrams that meet the
> guidelines, which shouldn't lean toward any particular tool, use it.
> Diagrams often assist knowledge transfer in ways not possible with just
> words, so let's make contributions easier rather than harder. Also, we
> should consider review options for diagrams similar to my suggestions for
> general content. If someone contributes a technically accurate diagram,
> almost anyone can modify it to meet guidelines.
>
> On Fri, May 13, 2016 at 11:40 AM, Shaun O'Meara <someara at mirantis.com>
> wrote:
>
>> First off let me say that I am not an advocate of any one tool over
>> another, none of the tools is perfect, and many are pretty horrible.
>>
>> Ideally I would like to be in a situation that as a contributor I have a
>> set of explicit guidelines and recommended tools that I can choose from to
>> contribute in the most effective and efficient way for me.
>>
>> To play devils advocate here, I don't believe that we can or should
>> dictate tooling, but we can provide explicit style guidelines.
>>
>> Thanks
>> Shaun
>>
>> On Friday, May 13, 2016, Matt Kassawara <mkassawara at gmail.com> wrote:
>>
>>> I think draw.io is one of the stronger plays, but has some of the same
>>> limitations as other online tools.
>>>
>>> On Fri, May 13, 2016 at 8:28 AM, Nate Archer <Nate.Archer at rackspace.com>
>>> wrote:
>>>
>>>> What is everyone’s thoughts on Draw.io <https://www.draw.io/>? I’ve
>>>> used in the past and while the toolset is somewhat limited, it has the
>>>> ability to save and open editable SVG’s, as well as the ability to export
>>>> the diagram as a PNG file.
>>>>
>>>> Downside is when you open an SVG file in Draw.io that has been created
>>>> in another tool, certain elements of the illustration might not show up.
>>>> This problem is mitigated if you use Draw.io exclusively, as with any
>>>> software.
>>>>
>>>> As Darren and Matt have pointed out, Inkscape is cumbersome to use, and
>>>> has many of the same problems as Draw.io, without any of the strengths.
>>>>
>>>> -Nate
>>>>
>>>> From: Matt Kassawara <mkassawara at gmail.com>
>>>> Date: Friday, May 13, 2016 at 7:36 AM
>>>> To: Christian Berendt <christian at berendt.io>
>>>> Cc: Olga Gusarenko <ogusarenko at mirantis.com>, Shaun OMeara <
>>>> shaun at omeara.co.za>, "someara at mirantis.com" <someara at mirantis.com>, "
>>>> openstack-docs at lists.openstack.org" <openstack-docs at lists.openstack.org>,
>>>> Rackspace Hosting <Nate.Archer at rackspace.com>, Darren Chan <
>>>> darren.chan at RACKSPACE.COM>
>>>> Subject: Re: [OpenStack-docs] Diagram recommendations for Openstack
>>>> Contributor Guides
>>>>
>>>> If you contribute diagrams, you'll quickly figure out that Inkscape is
>>>> difficult to use and produces rough content at best. If we want OpenStack
>>>> to appear more professional and less like a science experiment to our
>>>> increasingly less technical (read: decision makers) audience, we have to
>>>> use a tool that creates professional looking content. Some of the online
>>>> tools are surprisingly decent, so I wouldn't rule them out. Unfortunately,
>>>> regardless of what we use, we're never going to have standardized SVGs that
>>>> any online or installed tools can consistently parse.
>>>>
>>>> On Fri, May 13, 2016 at 3:46 AM, Christian Berendt <
>>>> christian at berendt.io> wrote:
>>>>
>>>>> On 13 May 2016 at 10:34:48, Shaun OMeara (shaun at omeara.co.za) wrote:
>>>>> > > Opensource
>>>>>
>>>>> With this requirement we are only able to use Inkscape, it is the only
>>>>> listed open source software.
>>>>>
>>>>> Omnigraffle, DrawSVG, and Lucidchart are not open sourced.
>>>>>
>>>>> I would prefer to not rely on hosted services like Lucidchart and
>>>>> DrawSVG. This way we are depending on the availability of a 3rd party
>>>>> service provider.
>>>>>
>>>>> Christian.
>>>>>
>>>>> --
>>>>> Christian Berendt
>>>>>
>>>>>
>>>>> _______________________________________________
>>>>> OpenStack-docs mailing list
>>>>> OpenStack-docs at lists.openstack.org
>>>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>>>>
>>>>
>>>>
>>>
>>
>> --
>> *Shaun O'Meara*
>> *Sr. Systems Architect*
>> *Mirantis, Inc*
>> *+27 (0)83 634 8904 <%2B27%20%280%2983%20634%208904> (South Africa)*
>> *+1 (628) 444 9094 <%2B1%20%28628%29%20444%209094> (USA)*
>> *www.mirantis.com <http://www.mirantis.com>*
>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160513/162c1ded/attachment.html>


More information about the OpenStack-docs mailing list