cleanup

[steveharoz]

The repository is getting a bit tough to navigate. I propose rearranging things.

• [x] Move each exemplar into its own RMD file
• [x] Sweep for any unused files
• [x] Rearrange the directory
  • root folder
  • guides folder
    • RMD files
    • references file
  • figures folder
  • files: RStudio, bookdown, css, and git

[steveharoz]

Thoughts? @mjskay @chatchavan @dragice

[chatchavan]

To my knowledge:

• _travis.yml needs to stay at the root
• the two .sh files can be moved (a minor revision in the scrips are needed)
• _bookdown.yml and _output.yml needs to be in the same directory level as all Rmd files.
• Due our decision to use "Knit-and-Merge" method, all Rmd files have to be in the same directory.

Side note: There's a standard directory format for R package, but it doesn't cover Rmds. It puts images and css files on a separate top-level directory to R files. Thus, it is, in my opinion, inappropriate for our work.

[mjskay]

• Agreed that R project structure is not the right fit. Looking at some other bookdown projects, there doesn't seem to be a common directory structure, so I vote we reorganize as we desire.

• Personally I prefer having boilerplatey things (config scripts, build scripts, what have you) live in the root directory as much as possible so that one can just look at a subfolder of interest and ignore the boilerplate stuff. So I'd be fine with a "guides" subfolder with Rmd's and a minimum of whatever else has to be in that folder to support the bookdown compilation process.

• I'd rather go "flat" than "deep", so if we need a "figures" subfolder I'd rather put it at the top-level than under "guides" (if that is possible with bookdown). Easier to reason about and find things.

• Is moving each exemplar into its own file possible while still outputting each topic (FAQ + exemplars) to its own file in bookdown? If we can't have those exemplars be in the same output file as the FAQ, I'm not sure I like that idea.

• I think we don't have any unused files presently. I deleted the unused design rationale doc, since it is in the wiki now. Perhaps we should document files and directory structure in the README to ensure this?

[steveharoz]

• I mainly want to separate content (which we want people to feel comfortable editing) from all the bookdown and R scaffolding (which most people shouldn't touch). And I'm ok with a root level "figures" directory.

• I tried splitting effectsize.rmd into effectsize_FAQ.rmd and effectsize_exemplars.rmd, and it outputted them as one chapter (I think it's because the exemplars file doesn't have a top level header).

• I got rid of one unused file, which is why I brought it up.

[chatchavan]

I tried splitting effectsize.rmd into effectsize_FAQ.rmd and effectsize_exemplars.rmd, and it outputted them as one chapter (I think it's because the exemplars file doesn't have a top level header).

I confirm this. The structure of the book depends on the level of the headers (i.e., the number of # you put in front of each header.)

I agree with other comments above. @steveharoz How about you reorganize the files in your fork? When you are done, point me to your fork. I'll make adjustments to bookdown and Travis scripts based on your fork before we merge everything back to the transparentstats/master together with configuring Travis (Issue: https://github.com/transparentstats/guidelines/issues/16 , PR: https://github.com/transparentstats/guidelines/pull/47 ).

[mjskay]

Agreed with Chat's suggestion on process. I also wouldn't wait on other pull requests (e.g. mine) to do this. Whatever gets in first will create a conflict with the other one, which it is then that person's responsibility to fix on their pull request. That's the beauty of git. :)

Also: we could even split each exemplar into its own file (like "effectsize_exemplar_simple.Rmd", "effectsize_exemplar_within.Rmd", ...). That will make adding one new exemplar to a guideline easier, and will also separate them in compilation (ensuring there are no accidental dependencies between two exemplars in the same guideline).

[steveharoz]

There's a bug in bookdown that's preventing this for now: https://github.com/rstudio/bookdown/issues/418

[shionguha]

All looks good - I just wanted to say - can we have a howto about process to generate exemplar formats when we've all figured it out since we want everything to look consistent? I just started working on Likert type formats but want to make sure before merging.

[chatchavan]

@shionguha Isn't the Style guide in the "Exemplar" section what you are looking for?

[mjskay]

I did the file split part in order to set up the pre-review PR. @steveharoz I leave the rest to you.