Since this is would be a big change, before making an issue and a pull request, I show below my proposal for reordering Stan Modeling Language document. If there are no objections, then I’ll make a pull request.

In the proposal I’ve used the current chapter numbers, but ordered them in a better order + some chapters would be combined as there is some unnecessary repetition. It would be possible also to move Section II to be the last Section, but I think this order would work also.

I Introduction

- Overview
- Model Building as Software Development

II Stan Modeling Language

27. Statements

25. Data Types and Variable Declarations

+ 3. Data Types

+ 4. Containers: Arrays, Vectors, and Matrices

+ 5. Multiple Indexing and Range Indexing

26. Expressions

29. Program Blocks

28. User-Defined Functions

24. Execution of a Stan Program

III Example Models and Programming Techniques

6. Regression Models

7. Time-Series Models

8. Missing Data & Partially Known Parameters

9. Truncated or Censored Data

10. Finite Mixtures

11. Measurement Error and Meta-Analysis

12. Latent Discrete Parameters

13. Sparse and Ragged Data Structures

14. Clustering Models

15. Gaussian Processes

16. Directions, Rotations, and Hyperspheres

17. Reparameterization & Change of Variables

18. Custom Probability Functions

19. User-Defined Functions

20. Solving Differential Equations

??. New section on LOO and k-fold-CV

58. Transformations of Constrained Variables

21. Problematic Posteriors

22. Optimizing Stan Code for Efficiency

+ 4.3 Efficiency Considerations

VIII Algorithms & Implementations

56. Bayesian Data Analysis

57. Markov Chain Monte Carlo Sampling

60. Hamiltonian Monte Carlo Sampling

55. Point Estimation and Optimization Algorithms

59. Variational Inference (+ 62. Variational Inference)

63. Diagnostic Mode

IV Built-In Functions

31. Void Functions

32. Integer-Valued Basic Functions

33. Real-Valued Basic Functions

34. Array Operations

35. Matrix Operations

36. Sparse Matrix Operations

37. Mixed Operations

38. Ordinary Differential Equation Solvers

V Discrete Distributions

39. Conventions for Probability Functions

40. Binary Distributions

41. Bounded Discrete Distributions

42. Unbounded Discrete Distributions

43. Multivariate Discrete Distributions

VI Continuous Distributions

44. Unbounded Continuous Distributions

45. Positive Continuous Distributions

46. Non-negative Continuous Distributions

47. Positive Lower-Bounded Probabilities

48. Continuous Distributions on [0, 1]

49. Circular Distributions

50. Bounded Continuous Probabilities

51. Distributions over Unbounded Vectors

52. Simplex Distributions

53. Correlation Matrix Distributions

54. Covariance Matrix Distributions

IX Software Process

64. Software Development Lifecycle ???

23. Reproducibility

X Contributed Modules

65. Contributed Modules

Appendices

A. Licensing

B. Stan for Users of BUGS

30. Modeling Language Syntax BNF

C. Stan Program Style Guide

D. Warning and Error Messages

E. Deprecated Features

F. Mathematical Functions

Bibliography