Create a page for contributors with clear instruction on what is required

[syclik]

Use the readme as an example.

• [ ] @syclik: decide where this document should go
• [ ] @bgoodri write the requirements in a clear language that can be understood by contributors and reviewers for what is required.
• [ ] @bgoodri some justification for these requirements? Maybe there's a simpler way to accomplish the same thing with less requirements.

[bgoodri]

@syclik Wherever you decide to put it, you can include the language based on point (3) on README.md:

For each Stan file(s), such as foo.stan and bar.stan, there MUST be a foo.data.R file and a bar.data.R file that use Stan's dump format in the same subdirectory as the corresponding .stan file (even if foo.data.R is the same as bar.data.R), regardless of whether foo.data.R contains simulated or observed data. This naming convention is essential for automated tools, such as the stan_demo function in the rstan package, that are asked to run foo.stan and need to know where to get the objects declared in the data block of foo.stan. It is essentially impossible for an automated tool to infer that a misnamed file such as, the_data_that_goes_with_foo.stan.R, contains the data that goes with foo.stan. In addition, it is essentially impossible for an automated tool to infer that the same data that were used in a previous chapter of a 500 page book are being reused for the Stan programs in a later chapter unless the data are copied into the subdirectory of each chapter that they are used. In addition, if you have a script in R or another language that generates data to use with foo.stan, do not under any circumstances name that file foo.data.R. Instead call it something like foo_generate_data.R and save the results in a file called foo.data.R. It is essentially impossible for an automated tool to infer how to call the functions in foo_generate_data.R, so a human has to do that.

On Mon, Feb 22, 2016 at 8:59 AM, Daniel Lee notifications@github.com wrote:

Use the readme as an example.

• @syclik https://github.com/syclik: decide where this document should go
• @bgoodri https://github.com/bgoodri write the requirements in a clear language that can be understood by contributors and reviewers for what is required.
• @bgoodri https://github.com/bgoodri some justification for these requirements? Maybe there's a simpler way to accomplish the same thing with less requirements.

— Reply to this email directly or view it on GitHub https://github.com/stan-dev/example-models/issues/45.