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!
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
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?