Bai-Li-NOAA
commented
6 months ago Following the agile documentation philosophy, the group is considering removing the model specification chapter from the developer's handbook. The proposal is to use Doxygen to publish equations with the source code, thereby avoiding the need to update equations in multiple locations. We plan to use design docs to document significant design decisions and archive them at the end of each milestone. The backup plan would be to continue working on the model specification chapter if we can't find a better way to navigate the Doxygen website.
Additionally, the group received feedback on adopting the Stan approach, which involves having separate components: (1) a user's guide containing clear implementation examples, (2) a reference manual providing background on model structure and syntax, and (3) a function reference offering more in-depth material of interest to a smaller subset of users.
Tasks
- [ ] explore better navigation of the Doxygen website. Examples of Doxygen websites: Example of output generated by doxygen, Eigen: Main Page , and ADMB Documentation: Function Reference @iantaylor-NOAA and @JonBrodziak
- [ ] Review the Doxygen website to confirm the documentation regarding model structure and syntax @Bai-Li-NOAA
- [ ] Learn more about the Stan approach and investigate whether they use automated tools to generate their documentation website @JonBrodziak
Any changes in model specification associated with MQ should be added to the https://github.com/NOAA-FIMS/collaborative_workflow/blob/main/03-M1-model-specification.Rmd file (will be renamed as part of #116).