Convert text-based examples to visual ones where that makes sense

[ianmackenzie]

I think many elm-geometry functions could be more easily explained with an image or two instead of looking at a bunch of numerical text output. For example, the current documentation example for Point3d.rotateAround is:

axis =
    Axis3d.x

angle =
    degrees 45

point =
    Point3d.fromCoordinates ( 3, 1, 0 )

Point3d.rotateAround axis angle point
--> Point3d.fromCoordinates ( 3, 0.7071, 0.7071 )

Ideally, I think the code example would simply be something like

p2 =
    Point3d.rotateAround axis (degrees 45) p1

and then there would be an SVG image showing the axis, the two points (labelled as p1 and p2), and maybe something like a dotted arc between the two points showing the rotation path.

For more complex examples, the image might actually be an iframe with an interactive example (written in Elm, of course!) that lets you drag input points, tweak numerical parameters etc. and see the output change.

This will require a significant amount of design and implementation work to come up with a nice consistent visual style for the examples and a convenient framework for generating the images.

[MrL1605]

Hi @ianmackenzie, I also felt the need for pictorial visualizations when going through the documentation. I would like to work on this and need more inputs from you.

While working on one of the issues here, I found a very good site which visualizes graphs by dropping points and equations.

Example chart for Bezier Curve It also supports embed iframe. Image generated from above link:

[MrL1605]

Or we could actually build a site similar to above mentioned at ianmackenzie.github.io/elm-geometry Which only has visualizations for methods in our package.

[ianmackenzie]

Hey @MrL1605 I think the first step would just be to generate a few more static images that can be included directly in the elm-geometry documentation for particularly tricky functions. I think at some point it will be valuable to have some separate, standalone documentation (in the form of a book, or a set of blog posts, or a wiki) but I'd like to think a bit more about what exactly that would look like. (By the way, it used to be possible to include iframes inside Elm package documentation, but that's no longer possible in Elm 0.19 - so if we want to include images inside documentation I think they will have to be static.)

And even for the static images I'd like to hold off for a little bit - I've been working on a high-level elm-2d-drawing package, and I think I'd like to finish an initial version of that and then try using it to generate the images (instead of using something lower-level like elm-geometry-svg).

What would be really useful is a list of functions where you thought a visual example would be useful (and, if possible, a description of what you found confusing). I can make guesses about what functions would be most useful to add visual examples to but it would be great to have some actual feedback!

[MrL1605]

Give me a week and I'll go through the current documentation and create a list of functions that I found were difficult to understand by current doc.

Then maybe we could update current documentation with images.

[ianmackenzie]

That would be great, thanks!