Symfony-docs: The new and redesigned Symfony Docs diagrams

[javiereguiluz]

Problem

A few months ago, we introduced the new Symfony Documentation. One of the pending tasks in our TODO list was to add more diagrams/illustrations and to redesign the existing ones.

We need to solve two problems:

1. Look for the right tool to create these diagrams.
2. Decide the style/design we want to apply to those diagrams.

The requirements for the tool must be:

• It must be free and open source.
• It must work offline and it must be installable.
• It must be cross-platform at least for Linux, Windows and macOS.
• It must export diagrams at least to SVG and PNG.
• It must be actively developed.

The requirements for the new design must be:

• The must look "professional", which means that they would look as if they were taken from a book of O'Reilly, Apress, Packt, etc.
• The fonts used in labels/text must be open source (or a equivalent free font license).

Solution

1. For the tool, I propose to use Libre Office Draw, which is the only tool I found to meet those requirements.
2. For the design, I propose to use a similar style to the books mentioned earlier.
3. For the fonts, I propose to use TeX Gyre Heros Condensed Regular, which is a free font.

And this is how this would look like in practice:

| Before (click image to enlarge it) | After (click image to enlarge it)
| --- | ---
| |

| New diagram for Security Guard (created by @a-ast in #7280)
| ---
|

We need your comments

Please share your comments about the proposed tool and design. Thanks!

[simshaun]

Did you happen to check out yEd? Admittedly, I haven't created many charts, but it's served me well when I've needed a few.

I'm not really a fan of the condensed font, but it does allow for tighter charts, if that's important.

Are the colors in the new Guard chart significant? In my opinion, colors don't really add value when I'm left wondering what they mean.

[wouterj]

Using LibreOffice just for drawing diagrams seems quite heavy for me. Besides that, I propose to use a font that'll already use on symfony.com. Otherwise, we end up with 4 different font families on the side, this seems not very coherent.

I quickly discussed this with some guys on IRC (credits to iltar and sfix!) and they came up with ditaa and PlantUML. Both tools work on a very great way: You type normal text and they transform it into an image. For instance, this example of ditaa:

    +--------+   +-------+    +-------+
    |        | --+ ditaa +--> |       |
    |  Text  |   +-------+    |diagram|
    |Document|   |!magic!|    |       |
    |     {d}|   |       |    |       |
    +---+----+   +-------+    +-------+
        :                         ^
        |       Lots of work      |
        +-------------------------+

Result:

The great thing about this is that these tools even have Sphinx extensions (in the sphinx contrib repository): sphinxcontrib-aafig (ditoo like) and sphinxcontrib-plantuml. PlantUML has more features, but a little less intuitive syntax. The advantage of PlantUML is that it's more recently updated than aafig. The good thing about the sphinx contrib library is that it's very likely that they'll support the latest Sphinx (they share the same maintainers).

I think these are very interesting tools to look at (and maybe similar ones?) as they allow us to maintain these diagrams very easy and don't require people installing tools like LibreOffice.

[javiereguiluz]

@simshaun thanks for your comments! Replying to your questions:

• I tried yEd. It's pretty similar to LibreOffice Draw but it has a big flaw. It's not Open Source. We can't trust any closed product for this.
• The reason for the condensed chart is what you said: it allows to make narrower diagrams. That's why most books used them. Some diagrams can be very complex, so this is a must in my opinion.
• About the colors, the charts are still an early draft. The reasoning was: the green and red can be understood without explanation; the blue one is only for the block diagram terminals to make them stand out a bit more.

[simshaun]

I tried yEd. It's pretty similar to LibreOffice Draw but it has a big flaw. It's not Open Source. We can't trust any closed product for this.

Gotcha.

The reasoning was: the green and red can be understood without explanation; the blue one is only for the block diagram terminals to make them stand out a bit more.

So, this may sound like a stupid question, but is there actually red in any of the charts you posted? I am partially color blind & only see the pastel blue & an extremely light pastel green (almost on the verge of light gray.)

[javiereguiluz]

@simshaun the authSuccess is green and authFailure is red, although these colors are very subtle. In any case, we'll never convey information through color. We are aware that 8% of males and 0.5% of females are blind to red-green (source) and there are a lot of other types of color blindness.

[robfrawley]

Very strong preference :+1: for Ditta or PlanetUML. The last thing I want to have to worry about is a GUI-bound, fully-fledged office suite when contributing to the Symfony docs (like Libre Office Draw).

[javiereguiluz]

Closing as fixed because we've already redesigned most diagrams and we've also added some instructions about how to do that: https://github.com/symfony/symfony-docs/tree/master/_images/sources