search

nhs-r-community / statements-on-tools

The NHS-R Community statements on the use of open source tools including (but not exclusively) R and R Studio.
https://tools.nhsrcommunity.com/
Creative Commons Zero v1.0 Universal
14 stars 9 forks source link

Chapter 3 content missing from PDF copy of handbook #42

Closed jlp-ds closed 1 year ago

jlp-ds commented 1 year ago

Sections 3.1 to 3.7 are currently missing from the PDF copy of the handbook (https://github.com/nhs-r-community/statements-on-tools/blob/main/docs/_main.pdf - starting from page 13), compared to the bookdown version hosted here: https://nhs-r-community.github.io/statements-on-tools/

ChrisBeeley commented 1 year ago

I'm unclear how the pdf is compiled. Is it a GitHub action? @tomjemmett could you please clarify?

tomjemmett commented 1 year ago

quick look, seems like our action redeploys the web version, but the docs folder is manually generated and committed.

We could build an action that generates the /docs folder and commits it to main, but I don't typically like this approach (potential for merge conflicts).

I think the better way would be to update the action to deploy the /docs to the github pages branch, and then update any links to point there. Finally, git -rm /docs from main

Lextuga007 commented 1 year ago

I didn't realise this was being published in pdf format and it's not in a stable state I think to warrant it. We must also be cautious about pdfs because of accessibility given Government guidance and so I tend to avoid them. Given that this is a book for compiling views, suggestions and experiences of tools, rather than a policy document, I'm not sure it necessarily needs to be available in pdf to share or archive.

Lextuga007 commented 1 year ago

Oops! Closed without any comment on closing - there is currently an issue with the GitHub action so this may need picking up in an issue that I'll create shortly.

ChrisBeeley commented 1 year ago

I think it's important to be clear that we're not "publishing" this document at all. It's a WIP.

PDFs are useful because GitHub will render them in the repo.

The public face of this repo is a github.io website in HTML, an accessible standard

Lextuga007 commented 1 year ago

I've removed the book outputs for now, particularly as I'm working on the content and there are many sections to add. I'm not at all keen on pdf as an output but can be convinced of it in conjunction with html for fixed, final drafts of documents so these may come back at a later date.

ChrisBeeley commented 1 year ago

It's still rendered on github.io so is that version out of date?

I don't agree that we shouldn't render a WIP (as long as it's clearly a WIP). I render markdown as I work on it to make it easier to read, so why shouldn't be render it on the repo? And will this document ever be "finished" anyway?

I think it's important to be clear that we are not publishing a pdf. It's a file in a repo. There will be lots of inaccessible files in the average repo.

When we do publish it, yes, let's have it super accessible, naturally