Organizing the GREL section in Docs

[Thad Guidry]

It felt a bit cumbersome, to initially read about the Expressions, and then not having a good flow when it came to reading it as a user manual.

I think we might want to re-organize things just a bit to help readability.

I know Owen had wanted to partition GREL functions and controls, and that's fine.

But they are not introduced at the same time, and really should be...where the user can then explore each set separately.

But currently, we have 1 set within the reading flow of Expressions.

And the other set on an entirely different page.

I think I would break this up a bit more now after having played with it for over a month.

I'd shorten the initial reading page of Expressions and mention the different parts in the Overview section...then provide in page links to those other pages of the docs.  Currently, it's all squeezed together in a paragraph and probably would be better as simple subheaders with links to the pages, or just bullet points with links to the pages.

Those new pages could be:

What do others think?

Thad

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

https://calendly.com/thadguidry/

[jonathan...@gmail.com]

First, I think the new user manual is superb – really readable and well laid out.

 

But the GREL section(s) do have the problems you mention. Would it make sense to group all the GREL/expressions paras together in an appendix? There would be more room, and it wouldn’t get in the way of the flow of the rest of the manual: GREL is not something everyone needs, or not at first. But it’s a vital section to many of us at some point. It could do with some use cases and examples.

 

Thanks a lot

 

Jonathan Stoneman

 

 

From: openr...@googlegroups.com <openr...@googlegroups.com> On Behalf Of Thad Guidry
Sent: 08 February 2021 19:25
To: openr...@googlegroups.com
Subject: [OpenRefine] Organizing the GREL section in Docs

 

It felt a bit cumbersome, to initially read about the Expressions, and then not having a good flow when it came to reading it as a user manual.

 

I think we might want to re-organize things just a bit to help readability.

I know Owen had wanted to partition GREL functions and controls, and that's fine.

But they are not introduced at the same time, and really should be...where the user can then explore each set separately.

But currently, we have 1 set within the reading flow of Expressions.

And the other set on an entirely different page.

 

I think I would break this up a bit more now after having played with it for over a month.

I'd shorten the initial reading page of Expressions and mention the different parts in the Overview section...then provide in page links to those other pages of the docs.  Currently, it's all squeezed together in a paragraph and probably would be better as simple subheaders with links to the pages, or just bullet points with links to the pages.

 

Those new pages could be:

 

 

What do others think?

 

Thad

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

https://calendly.com/thadguidry/

--
You received this message because you are subscribed to the Google Groups "OpenRefine" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openrefine+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/openrefine/CAChbWaOdbrn9%2BXJiWxgZX-8KOn6qyaWo03jMDxLv3Y1UyKq5Tw%40mail.gmail.com.

[allana...@gmail.com]

We definitely discussed, at the time, how the GREL reference isn't consistent with the flow of the rest of the docs. I'm happy to have a few more short pages just to keep things in order. Does anyone else want to chime in on this before I go ahead and make that change?

[Tom Morris]

It would seem to make sense to separate the reference material from the explanatory material, since it's somewhat bulky.  The explanatory material could introduce basic syntax, operators, controls, functions, etc and then the reference section could have sections for both controls and functions. The current functional groupings of functions could be supplemented with an alphabetical list.

Having said that, the current manual doesn't really seem to be structured as something to be read linearly, even though it nominally has "next page" arrows, so perhaps worrying about the "flow" isn't that critical.

Tom

To view this discussion on the web visit https://groups.google.com/d/msgid/openrefine/053ba58d-4176-411b-8e0e-7a46c57d4eean%40googlegroups.com.

[allana...@gmail.com]

I'm not keen on having an appendix; I don't see the need to pull anything out of where it is. I'd just make more page partitions.

Expressions

> Overview (Overview; Variables)

> GREL basics (Basics; Syntax; Controls, Constants)

> GREL functions

> Jython

> Clojure

There's no need for an alphabetical list when the search bar exists.

[Owen Stephens]

I'm happy to see this restructured based on feedback, but think it is probably worth us waiting until we have a full set of feedback before we start making changes.

My personal view is that if we end up wanting to separate out the GREL Expression reference, one option would be to have an additional top level option (at the same level as "User manual" and "Technical Reference"). I think this would be better than having an "Appendix" section in the User Manual, and I think there is some logic in separating out the GREL Reference. But I'm not sure this is necessary.

If we do go ahead as suggested then I'd suggest that we could group the Jython and Clojure parts together because they are pretty short sections and I'm not convinced these need a page each.

I also want to pick up on a couple of Tom's points:

>The current functional groupings of functions could be supplemented with an alphabetical list.

We did discuss this, but weren't (at the time) able to work out an effective way of having the list in multiple arrangements while only having the content stored once. If we can find a way of doing this in Docusaurus I'd be very happy to see it implemented (and to help implement it if necessary). As Allana says, in the meantime the search function helps bridge this gap, but my view is that having it possible for the user to explicitly filter the information in the GREL functions reference.

>Having said that, the current manual doesn't really seem to be structured as something to be read linearly, even though it nominally has "next page" arrows, so perhaps worrying about the "flow" isn't that critical.

I agree - as it stands this is meant to be a reference work, not a narrative. 

Best wishes

Owen

[Thad Guidry]

My personal view is that if we end up wanting to separate out the GREL Expression reference, one option would be to have an additional top level option (at the same level as "User manual" and "Technical Reference"). I think this would be better than having an "Appendix" section in the User Manual, and I think there is some logic in separating out the GREL Reference. But I'm not sure this is necessary.

oooh, I kinda like that idea actually.

If we do go ahead as suggested then I'd suggest that we could group the Jython and Clojure parts together because they are pretty short sections and I'm not convinced these need a page each.

sure, agree.

I also want to pick up on a couple of Tom's points:

>The current functional groupings of functions could be supplemented with an alphabetical list.

We did discuss this, but weren't (at the time) able to work out an effective way of having the list in multiple arrangements while only having the content stored once. If we can find a way of doing this in Docusaurus I'd be very happy to see it implemented (and to help implement it if necessary). As Allana says, in the meantime the search function helps bridge this gap, but my view is that having it possible for the user to explicitly filter the information in the GREL functions reference.

sure, agree we should try to provide an alphabetical listing for GREL functions.

>Having said that, the current manual doesn't really seem to be structured as something to be read linearly, even though it nominally has "next page" arrows, so perhaps worrying about the "flow" isn't that critical.

I agree - as it stands this is meant to be a reference work, not a narrative. 

ok, forget I said anything about flow.  Let me call it "organized structure", which is closer to what I was trying to say.  Oh wait, I did say it, in the subject line. :-) Ok, it wasn't such a bad day when I wrote this.

[allana...@gmail.com]

Hi - in draft for the moment (while I double-check some recent commits & update links), but ready to be discussed:

https://github.com/OpenRefine/OpenRefine/pull/3610/

I've split the original Expressions page into three (one for Jython & Clojure, but otherwise as I laid out in the comment above):

Expressions

> Overview (Overview; Variables)

> GREL basics (Basics; Syntax; Controls, Constants)

> GREL functions

> Jython & Clojure

Do we have any consensus that the GREL Functions Reference should be its own top-level item, alongside Manual and Technical Reference? I still think people will look under Expressions for a GREL reference so I'm against this change.

[Thad Guidry]

I thought that top-level items are just links to whatever you want?

If that is indeed the case, then we could just have the GREL Functions Reference on it's own page and having a link also under Expressions.

Thad

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

https://calendly.com/thadguidry/

[allana...@gmail.com]

Oh, I didn't know it worked like that - that would be great. I'll mess around with it and see what can be done.

[allana...@gmail.com]

Just remembered to upload this - you can see the preview here: https://deploy-preview-3610--openrefine-docs.netlify.app/

[Thad Guidry]

The preview looks really good Allana, Thanks!

There's a few GREL functions that are missing the formatting we decided to use ( if(), isError(), etc. ) in a few sentences I found on the grel#controls page: https://deploy-preview-3610--openrefine-docs.netlify.app/manual/grel#controls

Thad

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

https://calendly.com/thadguidry/

[allana...@gmail.com]

I assume you mean stuff like the way isError() is in plaintext in the sentence " Please note that the GREL control names are case-sensitive: for example, the isError() control can't be called with iserror(). "

We left it that way because we only `code` proper formulas (i.e., if it can be copy-pasted into OpenRefine and work). The names of functions (see also partition() a few paragraphs above) are not `code` styled.

If you mean something else, let me know!

[Thad Guidry]

OK thanks Allana.

Thad

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

https://calendly.com/thadguidry/