Preferred example style in documentation?

Request Feedback
#1

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?

#2

I would say that a simple argument against this is that a package author knows exactly what will happen when one of these examples is fired, whereas a user does not.

In your examples it may be extremely clear to you that originalPoint is of type Point3d, but that’s now implicit. The old example told me that, and if I were to use the new example only, maybe I would have tried ( 3, 1, 0 ) or [ 3, 1, 0 ] or { x = 3, y = 1, z = 0 } or something else before getting notified of an error at compile time. Perhaps you also just don’t explain the function in a way that everyone understands, but at the very least you give them an expected result they can play with. Not everyone is good a writing documentation, so I usually find playing with known results is the way I come to understand a new library rather than reading function docs.

Edit: Additionally, I really like your comment styles, even the multiline examples.

Initially, I was using

greedy [ 4, 5, 7, 6, 8 ] == ( [ 6, 7 ], [ 4, 5, 8 ] )

as a style choice, but this is only OK for extremely simple examples.

greedy [ 4, 5, 7, 6, 8 ]
--> ( [ 6, 7 ], [ 4, 5, 8 ] )

is far better and extensible in my opinion, so I changed them a few months ago because of elm-geometry's docs.

I guess what you’re trying to do is simplify your examples so that they don’t look too intimidating. To me, they’re already terse enough and explain a complex library well—oversimplification will just lead to confusion.

#3

Thanks for the thoughtful comments! General simplification is part of it, but another big part is that writing out things like Point3d.fromCoordinates will soon become even more verbose. I’m in the middle of updating elm-geometry to be based on elm-units, so

Point3d.fromCoordinates ( 3, 1, 0 )

will soon need to be

Point3d.fromCoordinates ( meters 3, meters 1, meters 0 )

or perhaps (if you’re being scrupulous about using qualified imports) even

Point3d.fromCoordinates ( Length.meters 3, Length.meters 1, Length.meters 0 )

In examples where everything has to be built up from scratch each time, this will add a lot of verbosity.

I wonder if perhaps there’s a compromise where I have an extended “full” example in the intro to each module that shows examples of a few different functions, something like

import Point3d
import Length exposing (meters, centimeters)

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

Point3d.distanceFrom Point3d.origin point
--> meters 3.162

displacement =
    Vector3d.fromComponents ( centimeters 5, centimeters 0, centimeters 10 )

point |> Point3d.translateBy displacement
--> Point3d.fromCoordinates ( meters 3.05, meters 1, meters 0.1 )

and then have individual function examples in the ‘compact’ style.

#4

Ah, I see what you’re getting at.

If you define a small set of helpers that you use all the way through the docs, then yeah—that will be a pretty good compromise.

Particularly with the way elm-geometry is set-up, you have a bunch of primitives (Point, Axis, Frame etc) that are then operated on (midpoint, centroid etc). Having a good understanding of how the primitives are constructed initially, then how they are operated on, seems to be the natural steps a user would want to absorb the package.

#5

I don’t think I’d actually want to reuse anything from the initial ‘full’ example in the rest of the docs - I find it annoying that to understand a particular function’s example you sometimes have to scroll back to the top of the page to see what it’s referring to, so I’d like to avoid that if possible.

I was hoping that an initial extended example would accomplish the goals of

  • having something you can play around with in a REPL
  • forming a rough mental model of the module (Point3d is an opaque type, there are functions to construct/query/transform points, etc.)

such that individual function examples could then be brief while still being understandable. (If you’ve seen a fully-worked example of rotateAround, then you probably don’t also need to see a fully-worked example of translateBy or mirrorAcross, since they work very similarly.)

#6

That’s what I was trying to get at for the most part, so I think we’re on the same page with your idea. I’d be happy to take a look again when you’ve fleshed out the plan a bit more and see if it still makes sense to me then. Perhaps ping me on github? @Libbum

1 Like
#7

I’m not sure if everyone knows that the --> syntax is used by elm-verify-examples to create tests that confirm that your docs snippets actually evaluate to what you claim they do. It’s a very useful tool and I recommend using it.

In my opinion, as long as you can make elm-verify-examples happy, you’re doing ok. If there are multiple variations that it accepts, use your best judgement and pick the one that is most clear.

#8

This topic was automatically closed 10 days after the last reply. New replies are no longer allowed.