nmfs-ost / ss3-doc

Source code for the Stock Synthesis manual and other documentation
https://nmfs-ost.github.io/ss3-website/
Creative Commons Zero v1.0 Universal
3 stars 2 forks source link

do we need to keep producing the PDF version of the User Manual? #136

Open iantaylor-NOAA opened 1 year ago

iantaylor-NOAA commented 1 year ago

I find myself only using the HTML version of the manual at https://nmfs-stock-synthesis.github.io/doc/SS330_User_Manual.html. I know there are people who print the PDF, but in theory the HTML could be printed too.

I think that the compiling issues discussed in #135 would go away and it would be easier to produce an accessible (Section 508 compliant) document in HTML only and in general the document would be easier to maintain.

The formatting of the HTML isn't as good as the PDF, especially for the tables, but I think that would be easier to improve if we were focused only on one format, not two. And it makes sense to focus the energy on the format that is easiest to use and maintain, which I think is the HTML.

kellijohnson-NOAA commented 1 year ago

I think that keeping the pdf will allow for easier publishing of updated technical memos if we care about that. Also, I do not think that an html version will ever print as nicely as a true pdf. I use to have a strong preference for keeping it but I will default to what others want. Maybe @Rick-Methot-NOAA has thoughts?

Rick-Methot-NOAA commented 1 year ago

I agree with maintaining capability to produce a pdf. I understand that Elizabeth was looking into conversion to Quarto, but do not know its status and how it interacts with the html/pdf issue.

iantaylor-NOAA commented 1 year ago

I think that the conversion to Quarto will definitely make adding to and revising the User Manual easier, and I'm guessing it will help with the PDF step too. I'm not sure on status of that work, but I think it's fine to have it be on hold until Elizabeth is back from her injury.

kellijohnson-NOAA commented 1 year ago

Quarto adds extra work to make the manual 508 compliant that I have not delved into as of yet. I personally advocate for native LaTeX as it currently is because you have more control but I understand that markdown is easier to read.

Rick-Methot-NOAA commented 1 year ago

I long for the days of WYSIWYG