Giters

merely-useful / py-rse

Research Software Engineering with Python course material

Home Page:http://third-bit.com/py-rse/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Proofreading comments

joelostblom opened this issue · comments

commented

Looks GREAT overall! Thank you for all the work getting this together. I went through it starting at the end to have fresher eyes on those sections, so most of my comments are there. All are minor:

  1. It looks a bit odd with all the white space at the end of page 20 after data/, not sure if there is a good solution. Similar but less noticeable on page 26.

  2. It would be nice if there was some indication for code blocks that span multiple page so it is clear that they are continuing on the next page. But unless there is some simple automated flag for this, let's skip it.

  3. The Appendix bookmark link to 15.1 Why we wrote this book, should there be an appendix title page inserted and linked to instead?

  4. In appendix E.2 and E.4 on ssh logins, is it confusing that we use > as the promptstring instead $ as we used in the bash chapters?

  5. There seems to be quite a lot of links in the glossary that do not work. I started going through it, but since there are so many I think it makes sense to go through all and either delete the link or add the entries. I think some of these did exist before (like Python and R?), so maybe we lost them in some big restructure (or I am missing something)?

    • Multiple entries have link to Python and R that don't work since there are no entries for these two.
    • makefile entry, the link to "Make" does not work because "Make" is not in the glossary so either remove the link or add Make.
    • JavaScript Object Notation, the second sentence is written in a way that suggest that the entry should be JSON instead.
    • Creative Commons license has a link to "licenses" that does not work.
    • code coverage (in testing) has a link to "library" that does not work
    • actual result (of test), links to passing and fails do not work
commented

Thanks for the feedback - I think we've now incorporated what we can, and yeah, the glossary hyperlinks were noted in #601. Would you like to tackle this one?

commented

Oh, I missed that issue! Sorry I wont be able to work on it any time soon, I'm drowning a bit at work. But if it is a longer term item not for the publication, I can help in a few weeks (maybe 4-5 weeks).