Provide distributed (per-module), current, and stylistically coherent diagrams

muziejus commented 6 years ago

I'll try to centralize the various threads between myself, @DenisCarriere, @rowanwins, @stebogit and anyone else who has been talking about images for the documentation.

1152 @denis sets up so that every module can have its own ./images directory. This moves us toward solving the first half of this goal, having distributed (per-module) images/diagrams. They are, of course, optional for any given module.
1140 @rowanwins brings up the issues of generalization, which suggests their being handled in the same way but also,
1128 as @stebogit notes, they should (but not must) use a consistent visual language.

Proposal:

Require all diagrams to be .svg format, following the naming convention of turf-${decamelizeName}.svg, say, or turf-center.svg. This sets up a problem when an image is duplicated, but svg is light enough that maybe that's not an issue and can be handled programmatically on build?
Have Travis/etc. build a .png of the .svg on build, if modified. I'm not an expert on this, but I can't imagine it'd be difficult to implement.
Build a .css style-sheet for the svg graphics, where we can use class names to provide visual consistency (stroke width, fill opacity). Looking at Esri's docs, it seems that there are a small number of primitives that have to be defined: a handful of polygon styles, points, and that's about it. These could either be enforced at the css level or
Bundle the .svgs together in an editable .pdf. Inkscape can pull pages from this pdf and work on them one at a time (though I'm not sure how rebundling it would work), while keeping them together in a single pdf allows for "master" changes in Illustrator. Now that the idea of using css has hit me, I'm a little less driven by the promise of visual consistency provided by having n artboards in AI. This pdf would be broken up into svgs, of course, and each svg would end up where it belongs on build.

DenisCarriere commented 6 years ago

@muziejus Try adding some .png or .jpg to the module repos and use npm run docs to build the new README.md.

Let me know if that works, for now .svg & .ai file extensions are ignored, so you can still store them in that folder if someone would want to re-create those diagrams with the Illustrator files.

muziejus commented 6 years ago

@DenisCarriere OK.

rowanwins commented 6 years ago

Gday all,

Sorry that this has taken a while longer than expected. Attached is my first cut at a graphic template with a bit of a style guide showing prefered fonts/colours as per the turf website. I've designed it in Inkscape so it's svg, it can be exported to whatever size png.

As a next step I might take a look at @muziejus diagram of center to see if the style guide can be usefully applied to that, that'll be a good test

turfgraphics

I was thinking it might be good to setup another repo in the turf organisation for some of this design-y stuff. I can drop the svg template, fonts etc in there. Are you able to do this @DenisCarriere ?

stebogit commented 6 years ago

👏 👍

Turfjs / turf

Provide distributed (per-module), current, and stylistically coherent diagrams #1154

1152 @denis sets up so that every module can have its own `./images` directory. This moves us toward solving the first half of this goal, having distributed (per-module) images/diagrams. They are, of course, optional for any given module.

1140 @rowanwins brings up the issues of generalization, which suggests their being handled in the same way but also,

1128 as @stebogit notes, they should (but not must) use a consistent visual language.

Turfjs / turf

Provide distributed (per-module), current, and stylistically coherent diagrams #1154

1152 @denis sets up so that every module can have its own ./images directory. This moves us toward solving the first half of this goal, having distributed (per-module) images/diagrams. They are, of course, optional for any given module.

1140 @rowanwins brings up the issues of generalization, which suggests their being handled in the same way but also,

1128 as @stebogit notes, they should (but not must) use a consistent visual language.

1152 @denis sets up so that every module can have its own `./images` directory. This moves us toward solving the first half of this goal, having distributed (per-module) images/diagrams. They are, of course, optional for any given module.