Identify gaps in documentation

[jonmaddock]

We believe we have many gaps in our documentation. This issue aims to capture any missing areas that are known about in the group, but have not yet been dealt with.

Please comment with any docs gaps that you are aware of, so we can get an idea of which areas need to be addressed, with a view to open-sourcing the code.

[jonmaddock]

In GitLab by @ajpearcey on Mar 29, 2023, 14:45

All cost models are not documented. Clearly the STEP model (cost_model=2) cannot be documented in detail. But, we should add detail on the others. This doc can form the basis of an explanation of cost_model=0 cost_model_1990_notes.pdf

Also the utilities section of the gitpages needs a overhaul.

[jonmaddock]

In GitLab by @ym1906 on Mar 29, 2023, 15:25

• I should review the plasma profiles section.
• A more user friendly guide to running PROCESS (best practises, how to interpret OUT.DAT, etc)
• Simple overview of models and how they interact?
• Remove Sam from Developers on intro page.

[jonmaddock]

In GitLab by @jmorris-uk on Mar 30, 2023, 09:53

#1805 is related and has some comments on docs.

[jonmaddock]

In GitLab by @ym1906 on Apr 13, 2023, 15:43

I've noticed a lot of the docs aren't formatted in the markdown nicely as they could be. Does it make sense to use a linter for markdown, or would that be too annoying/unfeasible?

[jonmaddock]

In GitLab by @mkovari on May 19, 2023, 11:40

I would list as number 1 priority improvement of the PROCESS Variable Descriptions (vardes.md). At present it does not show which variables are inputs and which are not. This makes PROCESS basically unusable except by inspecting the code.

Any suggestions @timothy-nunn ?

[jonmaddock]

In GitLab by @timothy-nunn on May 19, 2023, 13:57

Vardes is just to describe module variables. I'm not sure how we could say which variables are inputs 'automatically' as the tool just goes through and scrapes all the module variables.

There are a few options, none of which are very good:

1. Do it manually. Everything will get outdated very quickly :(
2. Write a Python script that parses input.f90 and indicates the inputs and default bounds... would probably work but at the cost of my sanity and would likely be very temperamental.
3. Wait until we Pythonise this bit, we will do it in a way that exposes this information in an easy way. I dont know when we will get around to this.

[jonmaddock]

Thanks all for these suggestions on gaps in the docs. These have been created as #2932, #2933, #2934, #2935 and #2936. This "identify" issue can now be closed.