FOR DISCUSSION: How should we approach documentation?

[Stephen Biggs-Fox]

We need a joined-up approach to documentation for consistency, clarity (in both the process and the documentation itself), ease of use, etc. This will help to avoid issues like #68 (Feature to stop run early but do so cleanly is not documented), which started to broaden out into a wider discussion about documentation, the relevant bits of which are copied below so that the discussion is all in one place:

SNBF: [Re issue #68] Where's the best place to document this?

Possibly this opens a wider discussion of how best to document GS2 in general? I mean, the in-code documentation is useful but it's more for developers. We could probably do with a short, simple user-manual to describe the basics of how to work GS2 and maybe that would be the place for this sort of information. A lot of the information for the user manual exists already in various places on the wiki, etc.

DD: The wiki is one place we could provide a quick-start guide. I'd quite like us to include this along side the auto generated source-code documentation so we have a quick start guided and top tips easily accessible.

SNBF: "I'd quite like us to include [a quick-start guide] along side the auto generated source-code documentation"

Do you mean we should configure FORD to generate some overview pages that don't relate to a specific bit of code but rather cover the program as a whole? If so, where does the source for that go?

DD: Yes exactly (see the "notes" part menu on the website) -- details are at https://github.com/Fortran-FOSS-Programmers/ford/wiki/Writing-Pages

SNBF: OK. So what's the plan then? Are we going to port the wiki to FORD format?

DD: No I don't think porting the full wiki to FORD is a good idea -- I think it makes more sense for us to curate a simple set of documents (at least to start with) that describe the key things we want to say. This should be more like a structured manual (perhaps also with a few standalone quick summary documents). The wiki still exists and can be used for more "wiki" like things. The ford docs ship with the code so are always available.

Designing and writing a manual is obviously time consuming work.

SNBF: Indeed. Do any of the current GS2 grants cover this sort of work?

The BOUT++ docs and the Dedalus docs both provide pretty good introductory user guides / tutorials. Maybe we could use one of these or a combination of the two as a template (or at least for ideas / inspiration)?

DD: Unfortunately I'm not sure if current GS2 grants do cover this or not. I agree that using something like BOUT's manual as an outline of the sorts of things we want is a good idea. In particular the separation of the manual into user and developer parts may be quite helpful in keeping the documentation focused.

SNBF: What about input parameters?

It seems that in-code documentation of the variable that appears in the namelist is a good way because it is more likely (although not guaranteed) to result in all current input parameters having documentation and removed input parameters also having their documentation removed.

Also, I'm fairly sure that namelists are only used in relation to input parameters. Therefore, it should, in theory, be safe to assume that all variables that are in a namelist are input parameters. This fact could be used to generate a master list of all input parameters and which namelist they're in with the in-code documentation alongside. Can we auto-generate a FORD page with this information on? Maybe the old wiki input parameters page could have its information ported to in-code documentation?

I'm asking because I'm adding a new input parameter in relation to issue #66 (Run fails if restart_dir does not exist) and I'm wondering where to put the documentation of the new input parameter. The above may be all well and good but is not set up yet and, while not too bad to implement, is not trivial either. What should I do about documentation of this new input parameter for now?

And an even broader question... how should we let other GS2 users / developers know about changes? I mean, most improvements, whether optimisations or new features, usually come with an input parameter to activate them. How can we make it easy for users / developers to keep up with such changes? (As opposed to bugfixes that can quietly fix things in the background.)

[Stephen Biggs-Fox]

DD: Yes input parameter documentation is probably the most important thing we need to provide to start with. FORD currently doesn't seem to be able to identify namelists -- one route forward is to contribute to ford to enable it to recognise namelists. We can then document these, but there may still be some things this can't achieve (e.g. getting the defaults).

For now I would use in source documentation, e.g. logical :: new_input=.true. !< Does the thing, default is .true.. We could think about documenting the namelist + defaults as part of the documentation of the routine responsible for reading that namelist (usually called read_parameters). It might require a bit of digging through the source documentation in order to find this, but at least it would be consistent.

I've been considering another approach that might better isolated the input parameters from the rest of the code, making it easier to document (and parse for auto-documentation). This approach may have several benefits but is a code change and could take a while to iron out (I've done this on other projects and it worked well, but it would be trickier for GS2).

We try to provide a change log with each release -- this is a good way to alert users to changes. Developers can use the change log but will hopefully also see the PRs that bring in these new features. It's therefore quite important to make sure PRs are as simple as possible (one feature per PR etc.) with a sensible title and good description (these are used to auto-generate the change log, at least partially).

[Stephen Biggs-Fox]

OK, thanks for that David. @Joseph Parker and @Peter Hill - do either of you have anything to add to this discussion at the moment?

[David Dickinson]

The start of this documentation is currently available at https://gyrokinetics.gitlab.io/gs2/page/index.html this includes auto-generated namelist documentation and outline of a developer and user manual (this will come and go depending on which branches are updated in the repository for a little bit). I’m going to close this issue now as we have issue #10 already tracking this (I think the intent of the issues is the same at least).

[David Dickinson]

Closing as duplicate of issue #10

[David Dickinson]

Duplicate of #10.