Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Refactoring the vignette #25

Closed
wlandau opened this issue Jul 1, 2018 · 4 comments
Closed

Refactoring the vignette #25

wlandau opened this issue Jul 1, 2018 · 4 comments
Labels
Ropensci issues

Comments

@wlandau
Copy link
Member

wlandau commented Jul 1, 2018 •
edited
Loading

Here, I do not think you need to repeat the motivation and installation sections from the README. After maybe a brief intro, you can jump right into usage. You may want to consider expanding the code chunk from #24. I recommend the following areas of focus:

  • Building and installing the package data packages.
  • Making it clear that the processed data enters the built package and the raw data is left out, but the source still has a reproducible record of the data processing.
  • Demonstrate loading the package and accessing the data.
  • The fields of the YAML file.
  • Data versioning
  • DATADIGEST
  • Partial builds and data migration as separate sections.
@wlandau
Copy link
Member Author

wlandau commented Jul 2, 2018

To be clear, the above list of sections is just a loose suggestion. I am only trying to give you some ideas, not trying to force you into a specific structure. This thread may also be helpful: ropensci/software-review-meta#55.

@wlandau wlandau mentioned this issue Jul 2, 2018
Closed
19 tasks
gfinak added a commit that referenced this issue Jul 5, 2018
@gfinak
Update the package vignette #25
d3554c6
gfinak added a commit that referenced this issue Jul 5, 2018
@gfinak
This commit and previous should address remaining ropensci reviewer i…
691e8e4 
…ssues.

#21 #22 #23 #24 #25 #26 #27 #28 #29 #30 #31 #32
@wlandau
Copy link
Member Author

wlandau commented Jul 8, 2018

I looked back over the vignette, and I see a lot of improvements here too. Just some comments on the draft in ee6ee6c:

  • You might consider moving "Why not use R CMD build" earlier, maybe when you introduce package_build(). It could even go under "Purpose", which is currently a bit terse for an intro section. Vignettes are very technical, and I recommend putting the least technical bits first and the most technical bits last, getting more and more advanced as the tutorial progresses.
  • Do you need a "Next steps" section? It currently only has a brief mention of git, not much for a major section heading. If you really want to provide guidance outside the scope of your package (and this is entirely up to you) it could go in a later final section, along with references to Jenny Bryan's Happy Git and GitHub for the useR book, Hadley's book on R packages, and other related learning resources.
  • Under "What's in the package skeleton structure?", there is a typo: mtcars2 instead of mtcars20.

gfinak added a commit that referenced this issue Jul 9, 2018
@gfinak
Address point 2 in #32
d6370fd 
- move YAML_CONFIG to vignettes.
Issue #24
- Add definition of data package to README.
Issue #25
- Move "R CMD build" to section after package_build is introduced.
- Extend the "Purpose" section a bit.
- Extended "Next Steps" and made it a sub-section.
- Referenced "Happy Git and Github for the useR" and Hadley's book on R packages.
- Fix typo mtcars2 to mtcars20
@gfinak
Copy link
Member

gfinak commented Jul 9, 2018

I believe the latest changes address the remaining comments on #24 and #25

@wlandau
Copy link
Member Author

wlandau commented Jul 10, 2018

Looks good, thanks.

@wlandau wlandau closed this as completed Jul 10, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Ropensci issues
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@gfinak @wlandau