Technical docs improvement (new-architecture)

[Thad Guidry]

Hi Antonin and devs,

In the technical docs
https://github.com/OpenRefine/OpenRefine/blob/new-architecture/docs/docs/technical-reference/workflow-execution/local-runner.md#L23
I see:

The concurrency in PLLs is implemented with Java threads. When instantiated, the local runner starts a thread pool which is used on demand when computations are executed.

Which computations?

Is this "any data transformations"?

Or is this really referring to the previous paragraphs describing some "compute".

Instead, the elements are computed on-demand

It's not clear enough if "data transformations" perform some "compute" and change elements on-demand in PLL's?  I know, I'm getting very picky here, but there's a reasoning behind it...read on.

Perhaps, it would be good to be more clear in that paragraph on what we are calling "computations" that can be executed.  I "think" I know what you are alluding to, but maybe not.

Perhaps link or relate it to other parts of our technical documentation?

Overall, I am beginning to think it might be good to have a clear understanding of the following terms used throughout our technical docs, maybe even at the beginning or later in a glossary.  How they overlap, synonomize, or differ:

- computations

- operations

- transformations

Thad

https://www.linkedin.com/in/thadguidry/

https://calendly.com/thadguidry/

[Antonin Delpeuch (lists)]

Hi Thad,

I have added a link to make it clearer, does that work for you?

Antonin

> <https://www.linkedin.com/in/thadguidry/>
> https://calendly.com/thadguidry/ <https://calendly.com/thadguidry/>
>
> --
> You received this message because you are subscribed to the Google
> Groups "OpenRefine Development" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to openrefine-de...@googlegroups.com
> <mailto:openrefine-de...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/openrefine-dev/CAChbWaMYDOfE%3DHpnsJr2WP%2Bjjfbn1wqm7opDWBcprqSenLuugA%40mail.gmail.com
> <https://groups.google.com/d/msgid/openrefine-dev/CAChbWaMYDOfE%3DHpnsJr2WP%2Bjjfbn1wqm7opDWBcprqSenLuugA%40mail.gmail.com?utm_medium=email&utm_source=footer>.

[Thad Guidry]

It's more helpful, Thanks!

Although "computation" isn't used on the linked to page but instead "operations".

It looks like PLL itself is said to be lazily-computed in our source?

But in CS it's often more common to see lazily-evaluated (call-by-need), especially in functional programming languages or as in our case, the need to avoid calculations until as late as possible or avoiding them completely.

"calculations" = "computations"

So I think that's why you introduced the term loosely there?

I think for PLL you can instead replace the context of "computed" with "created". Since that's the basic idea of lazy; being created on demand|created when needed.

Ex. https://commons.apache.org/proper/commons-collections/apidocs/org/apache/commons/collections4/ListUtils.html#lazyList-java.util.List-org.apache.commons.collections4.Factory-

In other areas, I think "computation" can be replaced with "evaluated".

Or leave as is, I understood the context, but not sure if a new contributor would, so that's my general worry.

Thad

https://www.linkedin.com/in/thadguidry/

https://calendly.com/thadguidry/

To unsubscribe from this group and stop receiving emails from it, send an email to openrefine-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/openrefine-dev/38f075e9-2c9b-34d9-02ab-17df626ef9a5%40antonin.delpeuch.eu.