I’m at a point where I am going to have to update a ton of documentation examples for my elm-geometry
package, and I’m wondering if this is an opportunity to tweak the example style to something more concise/readable. I’d love to get some feedback on what kinds of documentation examples are most useful!
Current style
Currently I’ve been trying to make examples complete and standalone (that you could basically just type into the REPL and have work), for example
However, this gets a bit unwieldy with more complex data structures - for example in my Arc3d
module I have a example arc defined near the top of the docs:
This then gets used to provide ‘complete’ examples for various functions:
It’s annoying to have to go back and look at the definition of exampleArc
each time, and the output is a fair bit of text to parse/interpret.
Proposed new style
I’m thinking of relaxing the ‘standalone’ requirement in favor of something shorter and more conversational, like:
(In this case I wouldn’t actually define originalPoint
or show the resulting coordinates of rotatedPoint
). Similarly,
Thoughts?
Is it useful to see fully-worked examples with actual numeric values in the docs, or is it enough just to have a description and example of the syntax, and fall back to elm repl
or Ellie if you want to see the details? Are there other styles that are even better?