mastodon
mastodon copied to clipboard
idaholab
Reorganize documentation
Currently, when we create a new material (with multiple classes, usually kernel, material classes and an action) we have the documentation for this material spread out in the documentation for all of these classes. We need a better organization.
My idea is as follows. For each new material (or other entity which involves creating multiple classes), we will create two new documentation files apart from the individual documentation for the classes. These two files are for theory (background and the math of the material/other entity) and user (how to use model this material, i.e., what classes to use or what actions to use.) We can then index all the theory doc files and the user doc files into the main theory and user manuals. This way, the theory and user manuals will be updated automatically every time we create a new material.
Looking at the current doc structure, I would move the "user" and "theory" folders to the top-level of doc/content. Also, "interfaces" should be moved to the "source" directory. Just my two cents.
May I suggest adding instructions for writing documentation in MASTODON, where this wording is explained and linked against some examples.
@aeslaughter, yes both sound good. I will do that.
@sveerara @hoffwm @colejust If you have any suggestions about how the documentation can be improved, please let me know.
@cbolisetti, i like both your suggestions and Andrew's suggestions on editing the documentation.
Should a test be added to check whether the theory and user documentation file exists for each .C file?
@sveerara, yes, I think a test like that would be very helpful. And perhaps generate user and theory stub files with a template too? @aeslaughter how difficult would it be to do this?
@sveerara, actually I don't think that would work since we need theory and user manual files for each material or BC, etc., and not each class. Should we check for it manually, if there's no other way?