We should probably only document Operations

[josephjclark]

I've just been doing some documentation work and I've got a whole bit about how "not all adaptor functions are operations".

And while that's technically true, there's only a small number of exceptions and I don't think any of them are designed for job writers.

Life would be a lot easier if we only publicly documented the actual Operations and hid everything else away.

[josephjclark]

@taylordowns2000 I'd appreciate your thoughts on this one! Do we want to be exposing stuff like this from common?

And if so, shouldn't it just be an operation which writes to state.data?

I sort of see the value of utility functions which you can use inside fn blocks and callbacks - in fact I've started designing adaptors around this pattern (with a utils file which exports stuff as utils). There are loads of common patterns which would be useful for job writers (although they probably favour functional programmers which maybe isn't the right audience for us).

But they really complicate the story. Something Aleksa said in Nairobi is that they weren't sure whether something was an Operation and whether/how they could use the return.

Maybe we think a bit later about splitting up Operations and Utilities in the docs.

[josephjclark]

Hmm - fields() is an example of a nice utility function which isn't an operation. Although if course it could be...