Update the technical description document

[k-doering-NOAA]

Imported from redmine, Issue #75177
Opened by @RickMethot on 2020-02-20
Status when imported: New

This would be a big project, but it seems worthwhile to move the technical description document into a git system, update and augment it, make it available as a living document in VLAB.

This seems like a few person-months of effort. Rationale for bringing another person onto the team (not necessarily to do just this). Your thoughts appreciated.

Rick

[k-doering-NOAA]

comment from @chantelwetzel-noaa on 2020-02-20:
I agree that the technical description needs to updated and converted to a version control system which would allow for future updating and dissemination among the user group. Converting the existing technical description would be a tedious task, but likely not terribly time-consuming (I think this could be done within a week). The part that I think would be the most time-consuming would be identifying what needs to be updated and expanding the description beyond the basic SS applications (e.g., additional selectivities, natural mortality approaches). It would be useful to do some scoping to identify how much of the description needs to be updated and how in-depth we want the documentation to be in order to understand the potential hours needed to complete this task.

[k-doering-NOAA]

comment from @RickMethot on 2020-02-20:
Thanks Chantel. I will make an initial pass through the document and create a google doc to contain my notes, which others can add to when you have a chance.

The need for this project is two-fold. One is the fact that it is out of date as I was reminded of when Adam Langley wrote me this morning to get info on the logL for mean length-at-age. The second is the growing chance that we will be able to launch a nextgen model project. A full description of SS will help.

I also am thinking that some of the essays created to describe SS3.30 will help.

[k-doering-NOAA]

@Rick-Methot-NOAA Does ths issue seem out of date to you, in light of @nschindler-noaa 's flowchart work? Feel free to close if so.

[Rick-Methot-NOAA]

The need still exists. It is related to the flowchart, but the flowchart will not have equations that describe what the code is intended to implement.

…

On Thu, Mar 18, 2021 at 2:16 PM Kathryn Doering ***@***.***> wrote: @Rick-Methot-NOAA <https://github.com/Rick-Methot-NOAA> Does ths issue seem out of date to you, in light of @nschindler-noaa <https://github.com/nschindler-noaa> 's flowchart work? Feel free to close if so. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABPV4ICZHCYOM7JHQ7BLNP3TEJUTVANCNFSM4TT46VBA> .

[chantelwetzel-noaa]

@k-doering-NOAA Thank you for the reminder on this. Do you think this should be located within a "Technical Description" folder inside the "doc" repository or should this be a stand alone repository? I can see pros and cons of each option. Once we decide upon the location, I plan on creating a Rmarkdown document (rather than LaTeX) that we can begin working on.

[k-doering-NOAA]

I love the idea of using Rmarkdown instead of LaTex - great plan! It will make it much simpler to render to HTML or pdf.

I think just putting into a folder of the doc repo would be great! I can also set up an automated compile routine once the R markdown doc is initialized.

[chantelwetzel-noaa]

Great! I will create the folder and start a Rmarkdown document today so it can be incorporated into the workflow. I suspect the completion of this document will take time but at least we will have a place to work when time permits.

[chantelwetzel-noaa]

Initial document started with commit 5491ecd

[Rick-Methot-NOAA]

OMG. This is huge news.

[chantelwetzel-noaa]

Don't get too excited yet since it is mostly a blank document waiting to be filled in at the moment. I am aiming to work a little bit on it every day to convert the existing technical documentation while creating space to add currently undocumented features.

[iantaylor-NOAA]

Not totally blank: https://github.com/nmfs-stock-synthesis/doc/blob/main/technical_description/_main.pdf

[k-doering-NOAA]

This currently doesn't have a github action to render it, but I would be happy to add it in the future. It shouldn't take too long to set up, so feel free to ask when it is needed @chantelwetzel-noaa