Open Stack

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<mailto:mkassawara at gmail.com>>
Date: Friday, May 13, 2016 at 1:08 PM
To: Shaun O'Meara <someara at mirantis.com<mailto:someara at mirantis.com>>
Cc: Rackspace Hosting <Nate.Archer at rackspace.com<mailto:Nate.Archer at rackspace.com>>, Christian Berendt <christian at berendt.io<mailto:christian at berendt.io>>, Olga Gusarenko <ogusarenko at mirantis.com<mailto:ogusarenko at mirantis.com>>, Shaun OMeara <shaun at omeara.co.za<mailto:shaun at omeara.co.za>>, "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>>, Darren Chan <darren.chan at RACKSPACE.COM<mailto: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<mailto: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<mailto:mkassawara at gmail.com>> wrote:
I think draw.io<http://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<tel:%2B27%20%280%2983%20634%208904> (South Africa)
+1 (628) 444 9094<tel:%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/6f556615/attachment.html>