Suggestions for improvements to documentation?

[cormullion]

@evanfields wrote a useful list of comments about the documentation from their perspective on Discourse, and I'll put it here in case anyone feels like commenting/making edits/disagreeing :)

1. Some curse of knowledge in the docs, where the neophyte reader has to infer basic things the docs author already knows. Ie: That a core workflow is the transform - draw from origin - untransform loop
2. Relatedly trying to keep track of absolute positions is probably doomed.
3. That all drawing is stateful and happens at global state. (I think…though now I wonder how different Pluto cells each with @drawsvg macros work.) The combination of global state + stateful drawing “feels” very different than most Julia code which seems to emphasize a highly functional side-effect-free style. Big brain shift.
4. That if you want to draw a series of connecting lines you need a polygon, not line
5. Some of the examples are, IMHO, “too clever.” E.g.: Even the first quick and short tutorial is doing clever things with colors and overlapping circles and rescaling, which takes precious brain cycles to parse for a new reader still literally trying to figure out which way is up.
   c = colors[mod1(n, end)]
   for i in 5:-0.1:1
   setcolor(rescale(i, 5, 1, 0.5, 3) .* c)
   circle(pos + (i/2, i/2), rescale(i, 5, 1, radius, radius/6), action = :fill)
   end
6. I will say that a lot of the docstrings on individual functions feel pretty sparse. The written explanations/tutorials are good, the reference is comprehensive, but the docstrings don’t connect to concepts. E.g. if I’ve just learned about moving the coordinate system, do I want move or translate? That took me a while. translate says “Translate the workspace to x and y or to pt .” which feels similar to move’s “move to a point”.
7. Why are there two coordinate systems, upper-left origin and center origin? Which do I want? Oh wait there are three, current coordinates are different. Can I just not use stateful transformations and work with a single global system?
8. What’s move vs translate?
9. Okay the matrix represents the current transformation, but why is it 2x3? Why do I keep hearing about 3x3 matrices? Why do the examples keep manually setting the matrix values? That doesn’t feel like “for tourists!” How do I apply a matrix to a point?
10. The docs mention that paths can have subpaths, but how do I create a subpath?
11. What if I want to make joined lines in a T shape, ie there’s one vertex with 3 lines coming out of it. Is that possible or do I have to make a L poly and then just add a line?
12. How can I create a polygon once and then draw copies of it?

[cormullion]

I made some updates to the documentation, which may address some of these comments.