CIME Users Guide Documentation

[bertinia]

I'm opening a new issue for the CIME Users Guide Documentation to coordinate
our efforts so that a technical writer at NCAR can review and update what is currently
posted at esmci.github.io/cime

Mariana sent out this email on 2-19-2017 with section assignments for the CIME Users Guide documentation on the gh-pages branch:

• @ekluzek and @billsacks l - can you look at the data model introduction and streams file input summary. Bill: Done Intro; gave streams file input summary a quick read
• @ekluzek - can you look at the data model datm section.
• @billsacks - can you look at the data model dlnd land section. DONE
• @dabail10 - can you please look at the data model docn and dice section.
• @mnlevy1981 - can you please look at the data model drof section.
• @jedwards4b - can you please look at the create_newcase and build sections in the user's guide.
• @bertinia - can you please look at the run section in the user's guide. DONE

Please update this issue ticket with the status for your section assignment so I can
coordinate with the tech writer.

[dabail10]

Things are looking good with DICE and DOCN that I can see. I have a few points though. The link to the SOM.pdf file is not working under the DOCN document. Also, it would be great to link to the bulletin board FAQ on this:

https://bb.cgd.ucar.edu/faq-data-ocean-slab-mode-docn-som

Also, I'm not sure about the convention for boldface, typewritten, italic. It looks like it is typewritten (double back quotes) for variables and file and directory names, but boldface (double asterixes) for some file and directory names. Is there a convention defined somewhere in the documentation? For the CICE User's Guide I do the following:

This document uses the following text conventions:
Variable names used in the code are typewritten.
Subroutine are given in italic.
File and directory names are in boldface.

Dave

[mnlevy1981]

The river runoff section is done as of b675ad8

commit b675ad8855a8f330ac93a5a747017180ebd51ddd
Author: Michael Levy <[email protected]>
Date:   Mon Feb 20 11:10:43 2017 -0700

    Clean up DROF documentation
    
    Mostly formatting changes (removing trailing spaces, formatting tables better,
    etc) but also fixed some typos). I changed all instances of "xml variables" to
    "XML variables", and also removed the table from the "Fields" section because
    it looks better inline.

[billsacks]

I still need to do some of this.... I updated the issue accordingly

[rljacob]

General Update from CIME telecon: BJ Smith completed his technical writing. Alice has his notes for gaps. Need to add: how to generate grids, user compsets. Larger glossary.

[bertinia]

@cacraigucar - moved you new issue #1764 as a comment on this open issue to keep all
CIME user's guides issues together.

The documentation (section 8.3) for creating a branch or hybrid run needs to be amended slightly. Right now it says to do a case.build prior to copying the restart files into the $RUNDIR. Since a preview_namelists is the first step of a case.build, this exits with a an error as the restart files are not found.

It also might be useful to describe briefly the difference between branch and hybrid on this page or have a link back to the descriptions in 6.3 for their definitions.

Also, when does a user want to use create_clone? The documentation on this is very sparse. A description on when to make a branch versus a clone would be useful.

For someone who is not "in the know" on hybrid/branch/clone, it was not very straightforward to work through this information.

[billsacks]

@bertinia I realized I dropped the ball on my responsibilities here (with respect to the data models), but I want to wrap this up. Before I look back at this: Is there anything outstanding / in the works with respect to the data model documentation, or is this in a state that's good to review as far as you know? (I know there are some changes to the documentation with #1950, but do you know of any other changes underway?)

[bertinia]

@billsacks - everything in master doc is up-to-date as far as I know w.r.t. the data models.
When you issue a PR associated with this open issue, just indicate that you would like the
the gh-pages orphan branch updated with the latest html.

[billsacks]

In #1969 I have finally fulfilled my assignments. However, I only skimmed 'input-streams'... I made some light edits but did not spend a lot of time on that section.

Also, I noticed that the data-wave section 11.2 doesn't match the layout of other data models... I haven't fixed this.

[cacraigucar]

@bertinia - I just looked at section 8 (create_clone) to help me with in setting up a create_clone run. It does not say what commands you need to issue after it and I needed to ask Jim. After speaking with him, case.setup is implied in a create_clone. A case.build needs to be run if --keepexe is not supplied. I would suggest having your examples (both with and without the --keepexe flag) include the ./case.submit step. In the first example without the --keepexe flag, you also need to add the ./case.build step to the example.

[cacraigucar]

./cime/config needs to be documented somewhere with the list of useful variables and needs to be updated with new variables as they are added (like the email selector)

[billsacks]

This issue was closed on the cime call because we felt that the primary issue (in the original comment) doesn't need any more done with it at this point. However, as I look back at this, I see that there are some comments that may or may not have been resolved. For people who made these comments, I'd suggest opening a new issue if you feel there's something that still needs to be addressed. (@cacraigucar we did discuss #1519 (comment) and @mvertens says that is in progress.)