Retrospective Consistency on Licensing Chapter of Guide to Reproducible Research

[paulowoicho]

Summary

Related to #1174 #1467, moved from #1388

With this PR I am addressing some of the consistency issues highlighted in the checklist from issue #1174 for the Licensing chapter of the Guide to Reproducible Research

List of changes proposed in this PR (pull-request)

• Split chapter into sections so that it is modular
• Edits to ensure correct grammar and tone using Grammarly (chapter uses American spelling, I left it as is)
• Added labels to headers to they can be cross-referenced
• Title-casing headers as appropriate
• Included a checklist and resources sub-section
• Converting images to MyST from markdown
• Changed formatting of checklist section

What should a reviewer concentrate their feedback on?

• Software Licensing subchapter was split in two for modularity. Is the split reasonable?
• License categories table was converted from HTML to Markdown. Does it still convey the intended message?
• Everything looks ok?

Acknowledging contributors

• All contributors to this pull request are already named in the table of contributors in the README file.
• The following people should be added to the table of contributors in the README file:

[netlify]

Deploy preview for the-turing-way ready!

Built with commit a718e78

https://deploy-preview-1460--the-turing-way.netlify.app

[martintoreilly]

Looking at the Netlify preview, I'm happy that the move to an image for the licences table restores the clarity lost by the table formatting raised in issue #1467. I'll leave final approval to @malvikasharan in terms of fit to the overall book look and feel.

[martintoreilly]

@paulowoicho Is there a source file for the JPEG licence table image? It would be good for this to be checked into version control so to make editing and regenerating the image easy.

[malvikasharan]

I agree with Martin on a clear description restored through this image.

I wanted to check in terms of accessibility:

1. Is there a way to have an alt text that explains the table, for example for the screen reader app? (I see that the next subchapter also have the table as images)
2. Red is color blind unfriendly and maybe not even needed in the context of this table. Without being too picky, is it ok to drop red altogether?

[martintoreilly]

@paulowoicho The alt text for the table image is really great!! 🚀 ✨ I like the new greyscale colour format too.

[paulowoicho]

Thank you @martintoreilly!

@paulowoicho Is there a source file for the JPEG licence table image? It would be good for this to be checked into version control so to make editing and regenerating the image easy.

I made the image as an MS Word doc, and took a screenshot of it for the commit. Would it be okay to check the word doc into version control? I could also recreate the image with an image editing software like photoshop.

@malvikasharan, does everything look okay?

[malvikasharan]

Looks great!! Thank you @paulowoicho and @martintoreilly. 🌺

As for the image, I agree to save a vector format for versioning purposes. Screenshots can't be updated. I wonder if word has an export image option like the ppts?

[martintoreilly]

Looks great!! Thank you @paulowoicho and @martintoreilly. 🌺

As for the image, I agree to save a vector format for versioning purposes. Screenshots can't be updated. I wonder if word has an export image option like the ppts?

We could potentially could check in the original HTML tables as source files, with a comment to take a screenshot and save as JPEG?

[martintoreilly]

Looks great!! Thank you @paulowoicho and @martintoreilly. 🌺
As for the image, I agree to save a vector format for versioning purposes. Screenshots can't be updated. I wonder if word has an export image option like the ppts?

We could potentially could check in the original HTML tables as source files, with a comment to take a screenshot and save as JPEG?

@paulowoicho @malvikasharan I've had a go at making the two software licencing tables with formatted HTML. I think this will be cleaner than using an image plus the source to build it. Let me know what you think.

[Edit: Potentially the table text could be a bit smaller than the main text?]

[martintoreilly]

I've proposed a few changes. Let me know what you think. Two in comments below and one in a new commit (the move to formatted HTML tables).

[martintoreilly]

I agree that starting numbering from 1 rather than 0 is more intuitive for our audience. However, the freedoms are numbered 0 to 3 in the original source linked to above, so I also worry about causing confusion due to lack of consistency between our presentation and this. What are your thoughts @malvikasharan?

@paulowoicho You only updated the reference to freedom 3 after renumbering the freedoms. This changes what the text originally said here. Having said that, I find the original wording a bit confusing.

@paulowoicho / @malvikasharan What do you think of this alternative summary of the rights provided by the 4 freedoms (numbering uses your proposed 1-4 labelling)?

These four freedoms together effectively neutralize copyright: freedoms 1 and 3 let you use the original software and share it with others, and freedoms 2 and 4 let you create derivative works based on the software and share these with others.

[paulowoicho]

Thanks @martintoreilly for catching this! I remember being confused with the wording here and I also didn't check the linked source.

I prefer your summary over the original -- I am making another commit to revert the numbering back to the 0-4, and including your summary, but with the original numbering.

@paulowoicho @malvikasharan I've had a go at making the two software licencing tables with formatted HTML. I think this will be cleaner than using an image plus the source to build it. Let me know what you think.

[Edit: Potentially the table text could be a bit smaller than the main text?]

I also really like how the tables have turned out with your approach, although I think some readers may confuse the table captions with the main text. As you suggested in #1467, It may mean that we might also now recommend this table style book-wide for consistency's sake.

Thanks so much for your review on my PR!

[martintoreilly]

I think some readers may confuse the table captions with the main text.

I've reduced the space between the table caption text and the footnote text at the bottom of the table. Does this make it bind with the table and separate enough from the main text? If not we can also look at making changes to font size, colour or style (e.g. italic).

As you suggested in #1467, It may mean that we might also now recommend this table style book-wide for consistency's sake.

I haven't figured out how to set styles book wide yet, but we should definitely pick a style and apply it consistently. On that front, I've also removed the alternate row shading from the table style, following the advice from this article that quotes Tufte. I've left the shading on the row and column headers as I think they help separate these from the data with the multi-row complex column headers, but I'm up for a discussion on what the standard style should be.

@malvikasharan Perhaps best to leave standardising table style across the book to another PR so we can discuss with the community but not block the content changes in this PR or delay the improvement to the readability for these particular tables?

[martintoreilly]

These four freedoms together effectively neutralize copyright: freedoms 1 and 3 let you use the original software and share it with others, and freedoms 2 and 4 let you create derivative works based on the software and share these with others.

I think the numberings got a bit garbled in the translation back to 0-3 numbering. I've made a commit to group the usage and modification rights as follows, keeping your style changes..

These four freedoms together effectively neutralize copyright; Freedoms 0 and 2 let you use the original software and share it with others. Freedoms 1 and 3 let you create derivative works based on the software and share these with others.