search

NOAA-EDAB / ecodata

A data package for reporting on Northeast Continental Shelf ecosystem status and trends.
https://noaa-edab.github.io/ecodata/
Other
31 stars 12 forks source link

Create clear instructions for internal package dev #9

Closed slarge closed 2 years ago

slarge commented 5 years ago

We need to:

slarge commented 5 years ago

Building off this idea, there are at least 3 ways to do this: readme.md, wiki, or vignette.

  1. readme.md seems like it should be simple and just describe the core functionality of the package and shouldn't get into the internals (e.g., how to add data, how to update and archive after SOE release, etc). I think the current readme.md is pretty solid and only needs a few tweaks for prime-time.
  2. I think the Wiki is a fine option, but after spending 10 minutes on it, it's not in the usual .rmd format and it seemed slow and tedious.
  3. I just poked around with vignettes, which on github display as package pages using super straightforward .rmd.

Votes?

andybeet commented 5 years ago

i think the readme should be used to explain what the package does, what it contains etc with some "getting started" tips

i think the vignette should be more of a how to use the package in a more in depth way, describe the list of functions, what they do, and how they are used together.

i know some of this can be included in individual help files but i feel like the vignette is better suited to describe the whole by its parts.

On 3/14/2019 5:12 PM, Scott Large wrote:

Building off this idea, there are at least 3 ways to do this: readme.md, wiki, or vignette.

  1. readme.md https://github.com/NOAA-EDAB/ecodata/blob/master/README.md seems like it should be simple and just describe the core functionality of the package and shouldn't get into the internals (e.g., how to add data, how to update and archive after SOE release, etc). I think the current readme.md is pretty solid and only needs a few tweaks for prime-time.
  2. I think the Wiki https://github.com/NOAA-EDAB/ecodata/wiki is a fine option, but after spending 10 minutes on it, it's not in the usual .rmd format and it seemed slow and tedious.
  3. I just poked around with vignettes, which on github display as package pages https://noaa-edab.github.io/ecodata/articles/ecodata.html using super straightforward .rmd https://raw.githubusercontent.com/NOAA-EDAB/ecodata/master/vignettes/ecodata.Rmd.

Votes?

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/NOAA-EDAB/ecodata/issues/9#issuecomment-473064907, or mute the thread https://github.com/notifications/unsubscribe-auth/AVajbTkf4eOKX-ZEnit8xz71m6j4Y15Lks5vWrsogaJpZM4ZN21O.

-- Andy Beet Ecosystem Dynamics & Assessment Branch Northeast Fisheries Science Center NOAA Fisheries Service 166 Water Street Woods Hole, MA 02543 tel: 508-495-2073

sgaichas commented 5 years ago

Agreed, vignettes are likely the best way to add the detail needed. I wanted a way to add Travis implementation documentation to the tech-memo repository, and wrote it in an .rmd only to find the Wiki wouldn't easily use that. A vignette may be the way to go for that too.

slucey commented 5 years ago

The vignette is a nice way to go and can be used inside R to figure out what you're doing.

Sean

Sean M. Lucey Fisheries Biologist Ecosystem Dynamics and Assessment Branch U. S. Dept. of Commerce/NOAA/NMFS Northeast Fisheries Science Center 166 Water Street, Woods Hole, MA 02543 508-495-2011 (voice) 508-495-2232 (fax)

On Thu, Mar 14, 2019 at 5:12 PM Scott Large notifications@github.com wrote:

Building off this idea, there are at least 3 ways to do this: readme.md, wiki, or vignette.

  1. readme.md https://github.com/NOAA-EDAB/ecodata/blob/master/README.md seems like it should be simple and just describe the core functionality of the package and shouldn't get into the internals (e.g., how to add data, how to update and archive after SOE release, etc). I think the current readme.md is pretty solid and only needs a few tweaks for prime-time.
  2. I think the Wiki https://github.com/NOAA-EDAB/ecodata/wiki is a fine option, but after spending 10 minutes on it, it's not in the usual .rmd format and it seemed slow and tedious.
  3. I just poked around with vignettes, which on github display as package pages https://noaa-edab.github.io/ecodata/articles/ecodata.html using super straightforward .rmd https://raw.githubusercontent.com/NOAA-EDAB/ecodata/master/vignettes/ecodata.Rmd .

Votes?

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/NOAA-EDAB/ecodata/issues/9#issuecomment-473064907, or mute the thread https://github.com/notifications/unsubscribe-auth/AFUeDu4ZaaMc7Cz8Dfpkq-LQ_uppph05ks5vWrsogaJpZM4ZN21O .

seanhardison1 commented 5 years ago

@sgaichas The "vignette" page for ecodata was developed from a one-liner in pkgdown, and might be a good way to create something similar for the tech-memo.

Pushing from ecodata to ERDDAP is not straightforward, since we'll need to find a way to access the comet server securely from R, but I'd be surprised if it weren't possible. A way around this would be to push data directly from the instance of R hosted on the server.

@slarge do you know which program was used to create the fisheryO workflow diagram?