Spring cleaning for stan-dev/stan wiki

Just a heads up that I reduced the number of wiki pages on stan-dev/stan from over 70 to around 11. Here’s the new top-level index page that goes over the new structure:

Lots of pages were consolidated together. Others were moved to either the docs directory or the design-docs directory. Others that felt like notes-to-self just got mailed back to their authors. Many were just entirely out of date and deleted.

The remaining pages could use some tender loving care. I didn’t go through them individually to consolidate and update sections. There was a lot of redundancy in what we had and some of that remains.

The biggest change that I’d like to put in next is to move the prior choice wiki to an appendix in the user’s guide. That’ll still give us a web link to point to. I didn’t want to move this one, though, as it’s hugely popular. Even after the content moves, I’ll leave a redirect for a year or more.

Also, I’d be amenable to further consolidation, say of “proposing algorithms” and “contributing functions” and of the three test pages. That’d bring the total number of pages down to 7 (not counting prior choice wiki), which seems manageable.


Also just a heads up that unless someone calls me off saying they want to do it, I’ll target the math lib the next time I feel like being productive. Here are the Wiki pages in math now:

Adding a new function with known gradients
Apache 2.0 License Evaluation
Autodiff testing framework
Automatic Differentiation Testing Framework
Checklist for adding a dependency to the Math library
Dependency Checklist for the Intel TBB
Dev: debug
Developer Doc
Distribution Tests
Implementing forward mode automatic differentiation
Include order of headers
Introduction to Stan Math for New Developers
MPI Parallelism
ODE stress test
ODE System Refactor
OpenCL GPU Routines
OpenCL Kernels
Parallel Asynchronous ODE Integration
Parallel reduce_sum project page
Quick Start
Roadmap for structured linear algebra and GP covariance functions
Supported external API
Threading Support
Updating Libraries
Windows Development Notes

You can see that there is another “adding a new function” page here and also general pages that can be consolidated. Plus, there’s a GP section in the stan-dev/stan adding new functiosn doc that eems to be repeated here. Plus what look like design docs that can be moved. We can probably get this down to a handful of pages, too.


This is great - inspired by this to spring-clean the CmdStan wiki.

the CmdStan dev process is the Stan dev process - 'nuff said - https://github.com/stan-dev/cmdstan/wiki


This is on my todo list.

The link should remain live - it’s referenced all over the place, but eventually it should link to the chapter in the users guide.

While we’re at it, the users guide etc need more descriptive names. I would suggest

  • Stan example models and best practice
  • The Stan Language
  • Stan functions and probability distributions

I’m not sure why those last two aren’t one doc - usually I need to dart between them.

Count me in, too.

Right—we’ll replace the page with a pointer to the relevant user’s guide appendix, not just remove it.

Originally, the reference manual, user’s guide, function reference, and CmdStan reference were all one doc called the “Stan Reference Manual and User’s Guide”. We could start bundling more of these and other docs together again and find new names. We’re using “reference manual” and “user’s guide” in their conventional ways, which I like.

Technically, we could separate the function library from the language and use a different function library with different names, in the same way that the C++ spec is split from the C++ standard library spec. I was just following that convention. The basic arithmetic should probably be in the reference manual by that reasoning now that I lay it out.

The split was also partly for modularity because the docs were getting huge and it seamed like a natural factorization. When we add a new function only the functions reference needs to change.

It seems inevitable that books get expanded and split around here. I predict BDA6 will be a 3-volume set. I wouldn’t be surprised to hear that Knuth set out to write a paper and got carried away with the backstory and wound up writing The Art of Computer Programming to make it easier to write his paper.

1 Like

These names are totally opaque to me and I had similar feedback from my students. So I’m not sure which convention it is. It frequently takes me more than one try to open the correct document. (Hence my suggestion of more descriptive names)

1 Like

“Reference Manual” to me is something that provides a set of concise definitions.

“Users Guide” puts things in context.

Go to the users guide for help. Go to the reference manual to settle bets.

1 Like

Just posting a comment from a recent new contributor in Math on getting started for devs.


I think merging the math and stan wikis and http://mc-stan.org/math/ and have one central developer docu would be helpful and easier to get people started.

1 Like

That’s next on the list. I coordinated with @syclik to make sure he was OK with moving things to stan-dev/stan.

1 Like

Oh, and I should’ve said feel free to do it yourself. I’ll get around to merging the stan-dev/math wiki into the stan-dev/stan wiki when I need some productive procrastination time.