Mechanisms for content review

[Georg Osang]

David and I (from IDEMS) had a meeting with Oscar and Steven (thanks for the discussions!) on Monday, and one topic we touched upon was how to review PreText books during the authoring process.

For our work in Kenya, Ethiopia and Ghana our teams are developing textbooks that are reviewed by a variety of people, many of whom don't have the expertise to work on the PTX files directly. In our case, it's both important to review the actual textbook content and the STACK questions that are included in the book.

For the STACK questions, I've written a script to insert review links at the bottom of each exercise (checkpoint), which you can see here: https://idemsinternational.github.io/Ethiopia-University-Basic-Maths-manual-demo/sec-distance-formula-and-equation-of.html The link takes you to a form where the ptx file that the question appears in and the XML file of the STACK questions are pre-filled. Reviews are then collected in a spreadsheet.

(Question related to that: is it possible to set a flag in the publication file to selectively hide or show certain PTX elements based on their attributes? For example, if I put my links as something like <a href="..." class="review"> and in the publication file set a flag review to true/false to show/hide these review links, is there some mechanism like that? Or can I access the target, e.g. pdf, html, in my elements to selectively show/hide them?)

More generally, as far as I'm aware, there is already a feature for a feedback button that appears at the bottom of every page, and that is configured via the publication files (/publication/html/feedback/@href). But it doesn't let us know which particular page/element in our book a review is for, so the reviewer has to manually describe where the issue is and the author has to manually find the file in order to fix the issue.

What we discussed on Monday is that it would be nice to have a review link to the left of every page element, akin to the way the permalink symbols work (that only show up when you hover there). The permalink XSLT is defined here (thanks Steven). This could use a different symbol, say a speech bubble, and clicking it would go to a templated link, e.g.:

• https://github.com/[user]/[repo]/issues/new?title=[title]&body=[body] where the repo URL is part of the publication config and title and body are pre-filled with information identifying the element the review is for (e.g. the permalink to the element; nice would also be the ptx file that the element is defined in)
• https://docs.google.com/forms/d/e/[form_id]/viewform?usp=pp_url&entry.[entry_id1]=[entry1]&entry.[entry_id2]=[entry2] where the form and entry ids are part of the configuration, and entry1 and entry2 would be the information identifying the PTX element
• mailto email address with the title and body of the email pre-filled?
  Note that the entries in the URL may have to be escaped using some kind of urlencode function (e.g. urllib.parse.urlencode() in python) as otherwise links with certain special symbols might not work.
  Rather than hard-coding these choices, maybe a templated URL could be part of the publication configuration, where I can use a specified set of variables in my template (e.g. title/name of the element, permalink, source ptx file... whatever is easy to get hold of?)

How feasible would this be?

[Andrew Scholer]

Georg - 

(Question related to that: is it possible to set a flag in the publication file to selectively hide or show certain PTX elements based on their attributes?

Check out Versions: https://pretextbook.org/doc/guide/html/publisher-versions.html

 

More generally, as far as I'm aware, there is already a feature for a feedback button...

How feasible would this be?

One person's opinion...
That sounds like a lot of custom logic specific to a particular project. I can see general interest in including the page in the URL of the default button as a query parameter (i.e. have it go to https://myfeedbackurl.com/feedback?page-identifier). But when you get to the level of filling in fields on a Google Form, that seems impractical to build as a general feature.

You might consider adding a custom JS file to reviewed projects to generate the review links. JS used to be how PreTeXt added the permalinks (they only recently migrated into the page build process). It used to be that on page load, JS would identify all the places to insert a permalink and do so. You can see that old code here:
https://github.com/PreTeXtBook/pretext/blob/d10d65737767eb2333cf47f1df6dcd1ada017b13/js/pretext_add_on.js#L312

You can use the string parameter "html.js.extra" to add a link to a JS file. So for review builds, you could include that string param to add a JS file that creates the exact links you want.


Andrew Scholer

[Georg Osang]

Hi Andrew,

Thanks for the helpful response! Versions looks very easy to use.

Google forms was just one example, github issues is another one (suggested by Steven). That's why I suggested templating.

https://myfeedbackurl.com/feedback?page-identifier is effectively another example, with the nice property that you can just append the page-identifier (instead of doing some kind of substitution). The additional information would just make it easier for authors to directly identify the file to make changes in.

I don't know what review cycles usually look like for PreText books, and what level of expertise reviewers commonly have.

I think in our setting it would be useful to have fine-grained identifiers for the element that is being reviewed automatically as part of the review; maybe in other settings that's not needed.

I'll take a look at the old JS code for permalinks and the use of string parameters. So basically, in my publisher file, inside the <version>

I would specify something like <stringparams html.js.extra="external/my_script.js" /> and it would include it on every HTML page?

Best,

Georg

--
You received this message because you are subscribed to a topic in the Google Groups "PreTeXt development" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/pretext-dev/wGEQVvtkeyA/unsubscribe.
To unsubscribe from this group and all its topics, send an email to pretext-dev...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/CACm44N81zT3bk2pq_mcuSsuaW6JDAaqtB_tnSMcKjTTSg-oG3A%40mail.gmail.com.

[Andrew Scholer]

There are some existing large-scale collaborations; maybe someone from one of those will chime in. But many works using PreTeXt are solo projects.

Correct, <stringparams html.js.extra="external/my_script.js" /> should add that link to every page in your book.

Andrew

You received this message because you are subscribed to the Google Groups "PreTeXt development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/CAHDrpCf5SwScSRXCF-L%2BoySXgddmyc1VToE1E191W4C2GWisvQ%40mail.gmail.com.

[Oscar Levin]

I had talked to Georg a bit about this idea on zoom.  I really like the idea of allowing an author to provide a version of a book that can be used to gather feedback at the block level.  Here is what I propose:

1. It would be easy to add a publication variable that allowed a few options for feedback gathering support (email, google forms, github), together with a URL for the base of that response (could be the email address, the google form, or the github repo).  

2. We insert feedback links just like we do permalinks, when the publication variable is set.  For now, such links could be styled similarly to the permalinks, but in the future there can be viewing options that turn them off or on or make them more prominent (for example, a button in the UI that lets the reader provide feedback could pop these links out so that they can be easily clicked).

Seems like this would be fairly straightforward for an optional but useful feature.  I'm happy to take the lead on implementing this.

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/CACm44N8FcZGQLT4Qtb0wmbZXh59pRnkGuwG%3D_E2O5YzjadvNLQ%40mail.gmail.com.

[Andrew Scholer]

Number 2 would be opt-in, correct?

I think that is what you are saying, just want to make sure "in the future there can be viewing options" doesn't mean "add them for all books and figure out how to turn them off later".

Andrew

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/CAOU9BaVSiZZ%2Bg5FjPP4fMEJeVGhHm%3D_FUyizJcugXJB_P84UrQ%40mail.gmail.com.

[Oscar Levin]

Right.  In the future, there can be options for viewing in books that have this feature enabled.

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/CACm44N9y%3DSLDcKqUME874rog4yFjTrYB4%2Bn99%2BcB5gBJ7r7PeQ%40mail.gmail.com.

[Rob Beezer]

I can say more later. But for now...

More than 15 years ago David F and I worked on the design of a system that would allow readers to submit suggestions and corrections in an embargo fashion, much like a pull request.

I can see the current proposal morphing into something with layers of editors and contributors and then being backed by a database.

Would a separate project make sense? Presuming PreTeXt source and PreTeXt HTML, enhanced as necessary for whatever functionality is needed? With some independence, but still tightly coupled?

Rob

>>>>>> <https://groups.google.com/d/msgid/pretext-dev/CACm44N81zT3bk2pq_mcuSsuaW6JDAaqtB_tnSMcKjTTSg-oG3A%40mail.gmail.com?utm_medium=email&utm_source=footer>
>>>>>> .

>>>>>>
>>>>> --
>>>>> You received this message because you are subscribed to the Google
>>>>> Groups "PreTeXt development" group.
>>>>> To unsubscribe from this group and stop receiving emails from it, send
>>>>> an email to pretext-dev...@googlegroups.com.
>>>>> To view this discussion visit
>>>>> https://groups.google.com/d/msgid/pretext-dev/CAHDrpCf5SwScSRXCF-L%2BoySXgddmyc1VToE1E191W4C2GWisvQ%40mail.gmail.com

>>>>> <https://groups.google.com/d/msgid/pretext-dev/CAHDrpCf5SwScSRXCF-L%2BoySXgddmyc1VToE1E191W4C2GWisvQ%40mail.gmail.com?utm_medium=email&utm_source=footer>
>>>>> .

>>>>>
>>>> --
>>>> You received this message because you are subscribed to the Google
>>>> Groups "PreTeXt development" group.
>>>> To unsubscribe from this group and stop receiving emails from it, send
>>>> an email to pretext-dev...@googlegroups.com.
>>>> To view this discussion visit

>>>> https://groups.google.com/d/msgid/pretext-dev/CACm44N8FcZGQLT4Qtb0wmbZXh59pRnkGuwG%3D_E2O5YzjadvNLQ%40mail.gmail.com
>>>> <https://groups.google.com/d/msgid/pretext-dev/CACm44N8FcZGQLT4Qtb0wmbZXh59pRnkGuwG%3D_E2O5YzjadvNLQ%40mail.gmail.com?utm_medium=email&utm_source=footer>
>>>> .

>>>>
>>> --
>>> You received this message because you are subscribed to the Google Groups
>>> "PreTeXt development" group.
>>> To unsubscribe from this group and stop receiving emails from it, send an
>>> email to pretext-dev...@googlegroups.com.
>>> To view this discussion visit

>>> https://groups.google.com/d/msgid/pretext-dev/CAOU9BaVSiZZ%2Bg5FjPP4fMEJeVGhHm%3D_FUyizJcugXJB_P84UrQ%40mail.gmail.com
>>> <https://groups.google.com/d/msgid/pretext-dev/CAOU9BaVSiZZ%2Bg5FjPP4fMEJeVGhHm%3D_FUyizJcugXJB_P84UrQ%40mail.gmail.com?utm_medium=email&utm_source=footer>
>>> .

>>>
>> --
>> You received this message because you are subscribed to the Google Groups
>> "PreTeXt development" group.
>> To unsubscribe from this group and stop receiving emails from it, send an
>> email to pretext-dev...@googlegroups.com.
>> To view this discussion visit

>> https://groups.google.com/d/msgid/pretext-dev/CACm44N9y%3DSLDcKqUME874rog4yFjTrYB4%2Bn99%2BcB5gBJ7r7PeQ%40mail.gmail.com
>> <https://groups.google.com/d/msgid/pretext-dev/CACm44N9y%3DSLDcKqUME874rog4yFjTrYB4%2Bn99%2BcB5gBJ7r7PeQ%40mail.gmail.com?utm_medium=email&utm_source=footer>
>> .
>>
>