search

stan-dev / example-models

Example models for Stan
http://mc-stan.org/
766 stars 478 forks source link

[WIP] Feature/math guide #192

Closed bbbales2 closed 3 years ago

bbbales2 commented 3 years ago

My first attempt was to write intro docs for all the new stuff in Stan. That started getting long and I was barely making it anywhere so I gave up. Rendered attempt is here

Then I tried to write a cheat sheet for all the new stuff in Stan. The idea being that things only needed roughly documented examples and a few words. It's still crazy long, not sure it will fit on a cheat sheet. Rendered cheat sheet is here

Now I am thinking that my best chance of finishing something is an "anatomy of a Stan function" document. For this, the goal would be to take an existing function and explain the file structure, tests, and add verbal descriptions of all the little different things inside it (and leave the technical description to the doxygen and examples to other functions).

Anyway putting this stuff up to share, not looking for merge.

bbbales2 commented 3 years ago

Judging from your comments @t4c1 you like the longer document? So it's fair to count that as a vote to just finish the longer thing instead of a cheat-sheet style doc?

t4c1 commented 3 years ago

Well the longer one will be more useful for new devs. Also it looks like 90% finished to me.

SteveBronder commented 3 years ago

fyi working on writing some stuff up based on this as well

bbbales2 commented 3 years ago

@SteveBronder feel free to edit here or move this to where you want to work on it.

Based on what Tadej said, I'm thinking ditch the cheat sheet (but I'll just leave it in for copy-pasting convenience)

bob-carpenter commented 3 years ago

Sounds great. @seantalts and I went through a whole lecture at StanCon Helsinki on how to add a function to the math library. And we didn't even cover all the doc we had written then. So this is a big problem. I also want to say that as long as what's there is correct, it doesn't matter if it's not 100% complete---it'll be an improvement on what we have.

bbbales2 commented 3 years ago

The new place to work on this is https://github.com/stan-dev/math/pull/2350.

I merged the comments from this thread into that.