consistent arch diagrams and images in docs

[peterj]

At some point we should decide on a "style" and re-draw the diagrams across the docs, so they are all consistent and look & feel as they are part of the same product.

Existing resources

• Latest Istio brand guidelines
• Existing "Diagram creation guidelines" page that would need to be updated based on the brand guidelines
• Library of drawings (.svgs) for Istio.io

TODOs

• [ ] Update the diagram creation guidelines to match the brand guidelines
• [ ] Create and publish a shared Excalidraw (or other) library of components/icons that are on brand
• [ ] Update diagrams in the docs to match the new style

[craigbox]

https://drive.google.com/file/d/1YRY7TYSfrkAbpHuYPjdeHUwZMMzDlPvh/view came with the 2020 design and is a good place to start. Want to see if you can get something templated that looks/feels like that?

[peterj]

Yep, I don't mind the look & feel, it's mostly about staying consistent throughout the documentation and updating the diagrams that don't fit the same look and feel. For example:

[craigbox]

(No disrespect to the authors, but all three are butt ugly, and I can point you to a dozen more!)

I don't think Excalidraw is going to cut it btw - I'm thinking we need Illustrator templates or something like Canva.

[peterj]

we can re-draw in other software, but then we’d need a process for adding any new diagrams and have someone draw them in a nicer looking way

On Mon, Jun 3, 2024 at 17:43 Craig Box @.***> wrote:

(No disrespect to the authors, but all three are butt ugly, and I can point you to a dozen more!)

I don't think Excalidraw is going to cut it btw - I'm thinking we need Illustrator templates or something like Canva.

— Reply to this email directly, view it on GitHub https://github.com/istio/istio.io/issues/15195#issuecomment-2146358077, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACURJ3BR7QPYGCEATSPTBHTZFUERXAVCNFSM6AAAAABIPOZTCWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCNBWGM2TQMBXG4 . You are receiving this because you authored the thread.Message ID: @.***>

[craigbox]

We should optimize for whatever is the most likely to deliver consistent, nice looking output, that any contributor can easily access.

Then I can put a manual lint gate on people who don't submit drawings that look like the rest of the site in their blog posts 😁

(Maybe Google Slides isn't a bad choice?)

[craigbox]

It's working for me so far.

https://docs.google.com/presentation/d/1p1bMhB6hIw9bucb1qeiXRXwxODZlrXI2-Gjtv_b9x94/edit#slide=id.g2ec15086a55_0_0

I think the next step would be to identify the things we want to be able to distinguish between (i.e. a colour that means data plane traffic and a colour that means control plane/configuration traffic) and then put together an upgrade to the diagram components guide.

[peterj]

I'll update the existing creation guidelines according to the new design (https://istio.io/latest/docs/releases/contribute/diagrams/).

From there, we can fan out and have multiple people (if needed) help out with re-creating the diagrams based on these guidelines

[ilrudie]

mermaid maybe? Just brainstorming