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
#45.