Finalize documentation about bayesplot HOT 7 CLOSED

@paul-buerkner mind taking a look at the (very rough) drafts of the vignettes? In the MCMC vignette I added a mention of brms (line 38), but I use draws from rstanarm to demonstrate the bayesplot functionality. Maybe we could add an example using brms in the PPC vignette?

from bayesplot.

I will take a look and propose an example for the ppc vignette.

from bayesplot.

I think the vignette already look pretty solid at least from my perspective as the user gets a clear understanding of how to apply the bayesplot package. Should we add the missing paragraphs in the ppc vignette for the first release or just mention that this will come in the future?

After thinking about it a bit more, I don't think we should really add a brms example, since it requires compiling every model, which will almost certainly lead to problems when done in vignettes.
We could do two things though: (a) Also mention brms in the vignettes when mentioning rstanarm in the way you already did in the MCMC vignette and (b) Pointing to the pp_check method of brms as an example when disussing the pp_check generic.

from bayesplot.

I have read all the help pages. They are very detailed and thorough from my perspective. Most R packages never come close to this level of documentation. I have only a few minor comments:

bayesplot-convenience:

• I see why you write "v" in code style within "value", but it doesn't look that good from my perspective.
• the argument on is not clear just be reading its argument definition. You have to know to which functions it applies to make sense.

extractors:

• Instead of (melt) you could write (see melt)

from bayesplot.

On Tuesday, September 6, 2016, Paul-Christian Bürkner <
[email protected]> wrote:

I think the vignette already look pretty solid at least from my
perspective as the user gets a clear understanding of how to apply the
bayesplot package. Should we add the missing paragraphs in the ppc
vignette for the first release or just mention that this will come in the
future?

I guess not a big deal if we don't get to it for the first release since
there are examples on the help pages, but in general I like treating these
releases as real software releases so it's a bit strange to have missing
paragraphs in any documentation. But it's certainly not a huge problem.

After thinking about it a bit more, I don't think we should really add a
brms example, since it requires compiling every model, which will
almost certainly lead to problems when done in vignettes.
We could do two things though: (a) Also mention brms in the vignettes
when mentioning rstanarm in the way you already did in the MCMC
vignette and (b) Pointing to the pp_check method of brms as an example
when disussing the pp_check generic.

Ok sounds good!

from bayesplot.

On Tuesday, September 6, 2016, Paul-Christian Bürkner <
[email protected]> wrote:

I have read all the help pages. They are very detailed and thorough from
my perspective.

Ok great, glad to hear that.

Most R packages never come close to this level of documentation.

Yeah, the documentation in R itself and also in the majority of contributed
packages is a disaster. I won't go on my full rant about this, just a minor
one. I think it's an embarrassment that everyone is pretty much aware of
this situation and it still doesn't change. There seems to be some sort of
tacit agreement that's it's not really such a big deal. I think it's a huge
deal, not only because of the lack of documentation (which is a big deal
itself) but also because, in my experience, poor quality of documentation
is associated with poor quality of code (carelessness in testing, brittle
functions that work well when used exactly as the author intended but fail
mysteriously when used in other seemingly allowed ways, etc.)

Anyway, I try write to documentation as, or even before, I write the
code. I find that writing thorough documentation forces me to
really understand what the code does and what it doesn't do, which, as I'm
sure you know, is usually less obvious than it sounds (especially with R).

I have only a few minor comments:

bayesplot-convenience:

• I see why you write "v" in code style within "value", but it doesn't
  look that good from my perspective.
• the argument on is not clear just be reading its argument
  definition. You have to know to which functions it applies to make sense.

extractors:

• Instead of (melt) you could write (see melt)

Thanks, I'll take care of those.

from bayesplot.

Copying from above:

• Also mention brms in the vignettes when mentioning rstanarm in the way you already did in the MCMC vignette and
• Point to the pp_check method of brms as an example when discussing the pp_check generic.

from bayesplot.