[OpenStack-docs] Diagram recommendations for Openstack Contributor Guides

Shaun OMeara shaun at omeara.co.za
Fri May 13 08:34:14 UTC 2016


Hi Nate

Thanks for reaching out and starting the thread.

I have been doing a bit of research on options for an open diagramming, the
following is a high level summary of what I have been looking at;

*Diagram Tools and Standards*

*Rendering*

   - Diagrams should be rendered as PNG files, with the originals stored as
   SVG files.

*Original Files*

   - Original files should be stored in the some structure as the image
   files.

Requirements for tooling

   - Support SVG as an output type
   - Support SVG as in a input file
   - Support PNG image export
   - Opensource
   - Free or minimal cost
   - Easy to use
   - Programatically create image

*Online Tools*

* Lucidchart **- **https://www.lucidchart.com* <https://www.lucidchart.com>

* DrawSVG **- **http://www.drawsvg.org/* <http://www.drawsvg.org/>


*Installed Tools*

* Inkscape **- **https://inkscape.org/* <https://inkscape.org/>

* Omnigraffle **- **https://www.omnigroup.com/omnigraffle
<https://www.omnigroup.com/omnigraffle>*

With regards to Olga's comments, I have started writing a spec for this,
which I will share in the next couple of days.

Once we have decided and agreed on the tools and standards we can then
start working on a plan to refactor the existing diagrams.

Just an aside: I have also been looking ta GraphViz as and option to
programatically create diagrams using the DOT language.

Regards
Shaun


On Fri, May 13, 2016 at 9:44 AM, Olga Gusarenko <ogusarenko at mirantis.com>
wrote:

> Hello, Nate!
> Thanks for raising the point, and welcome to docs!
>
> + Linette Williams to the discussion. Linette, you probably have something
> to contribute here.
>
> As we discussed with Saun and the team on the Summit, the initial plan is
> as follows:
>
>    1. Create the templates for the diagrams (a set of images one can
>    construct anything they want using them).
>    2. Found the tool(s) one could import the templates to it and use it
>    for free.
>    3. Add the diagram recommendations to the contributor guide.
>    4. [future] Revise the existing diagrams.
>
> I can think of quite a big number of questions to discuss, argue =), and
> agree upon, and it makes sense to create a spec for this.
>
> What do you think?
>
>
>
> On Fri, May 13, 2016 at 12:17 AM, Matt Kassawara <mkassawara at gmail.com>
> wrote:
>
>> A good chunk of the existing diagrams were made in OmniGraffle... mostly
>> because it provides the path of least resistance in terms of time and
>> effort to generate useful diagrams. The documentation build system uses PNG
>> files, a raster format, so we request that any diagrams also include an
>> editable vector version in a separate file, typically something relatively
>> open such as SVG. However, as it turns out, no diagram tool seems to agree
>> on SVG file format, so it often helps to include a third file of the
>> diagram in the native format. The next problem we face is how to instruct
>> new people to make diagrams that conform to some sort of usable standard.
>> Not as easy as words, and explanations of things like line width or shading
>> often depend on the particular application. So, during the Newton cycle,
>> we'd like to determine how to define standards for diagrams and then add
>> them to the contributor guide.
>>
>> On Thu, May 12, 2016 at 11:53 AM, Nate Archer <Nate.Archer at rackspace.com>
>> wrote:
>>
>>> Shaun:
>>>
>>> My name is Nate Archer. I’m an information developer at Rackspace
>>> looking to become more involved with Openstack.
>>>
>>> Lana Brindley and Darren Chan gave me your name. During the docs
>>> planning at Summit, you discussed putting together some diagram
>>> recommendations for the Openstack contributor guides. Also in this
>>> discussion was Olga, Linnete, Piet, and Matt.
>>>
>>> I’m starting this email thread as a way of beginning the conversation
>>> about diagrams.
>>>
>>> As a newbie to Openstack, I would really love to see an updated version
>>> of the Logical Architecture diagram for the Ironic contributor guide.
>>>
>>> Do you have any ideas or thoughts?
>>>
>>> Regards,
>>>
>>> Nate Archer
>>> Information Developer I
>>> Nate.archer at rackspace.com
>>>
>>>
>>> _______________________________________________
>>> OpenStack-docs mailing list
>>> OpenStack-docs at lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>>
>>>
>>
>> _______________________________________________
>> OpenStack-docs mailing list
>> OpenStack-docs at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>
>>
>
>
> --
> Best regards,
> Olga Gusarenko
>
> Technical Writer | Mirantis, Kharkiv | 38, Lenin av., Kharkiv, Ukraine
> ogusarenko at mirantis.com | skype: gusarenko.olga | +38 (050) 843-14-25
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160513/d5e26cfd/attachment.html>


More information about the OpenStack-docs mailing list