docs: Add a diagram giving an overview of the plugin workflow

[euanh]

Motivation

On first visit to the repository or the documentation, it can be difficult to understand what the plugin does and how it fits into the development process. A flow diagram showing how the code is built, packaged, uploaded and deployed is much easier to read at a glance than a screen of example command output. The diagram can also provide a structure which can be referred to in the text.

Modifications

• Add a workflow diagram image
• Rewrite the overview section of README.md and the DocC documentation entry point to include the image and expand on what happens in each step.

Result

New visitors to the repository or the documentation will see a diagram which summarises what the plugin does and where it fits in the Swift Package Manager workflow.

Test Plan

All existing tests continue to pass.
Manually tested all new URLs.

[heckj]

The png may be a little awkward when viewed in dark mode due to the transparency and the cloud portion, but short of making an explicit light and dark version it conveys perfectly what you're after.

Content updates look great

[euanh]

Thanks @heckj. Is there a style guide for making graphics which work well in light and dark mode? I did ask for feedback from a dark mode user who said it looked ok.

I've played around with using a bit more transparency so that the diagram has similar contrast in light and dark mode. I didn't want to have too much white because it causes glare in dark mode. I don't want to increase the size of the repo more than necessary, so I'd rather stick to just one version of the image.

The final version of the diagram - with extra transparency in the cloud, the box and multi-file stack - looks like this in light and dark modes:

[euanh]

Argh, I forgot to include the optimised image in the final PR. 😞

Optimising it reduces the size from about 80kB to 20kB. That download cost will be paid every time someone adds the plugin to a project, so I decided it was worth the disruption of force pushing the optimised version to main.

[heckj]

No explicit style guide that I'm aware of - only the advice I've received in the past. There's a naming convention that DocC supports for images in multiple resolutions and different color schemes (aka adding ~dark for the dark mode version of an image) - detailed at https://www.swift.org/documentation/docc/adding-images, but that's all I've got in terms of references. Thanks for sharing the result images in both modes, it's a little low contrast for my eyes, but better than I had thought it might play out just looking at the PR image