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:
Home
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.
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.
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)
Just posting a comment from a recent new contributor in Math on getting started for devs.
Quoting:
I think merging the math and stan wikis and Stan Math Library: Stan Math Library Docs and have one central developer docu would be helpful and easier to get people started.
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.