Distinguish user- from developer-facing docs

[wpbonelli]

General principle for flopy docs, but also pertinent to the MF6 IO guide.

(I am partly writing this here to solidify the thinking before potentially raising it in the context of MF6. We are already making this distinction in some places, but the IO guide contains some developer-facing concepts IMO.)

People only using and not developing the program likely don't care (and shouldn't be forced to attend to) exactly how it works.

This is a more useful distinction when it comes to incidental complexity introduced by the program or platform, than details of the hydrological model. It's important for the modeler to understand how the model works, at least at a high level. But the system underlying the model should be presented to the user abstractly, not in the same terms developers use to implement it. (If there is a good reason for these to coincide, i.e. the developer concept is no more complex than the user concept, that seems fine though.)

On the MF6 side, the IO guide describes array input in terms of "a generic READARRAY capability", frequently mentions Fortran concepts in the same section, and refers to the program's source code. These seem like developer-facing details — the user wants to know how to write correctly formatted input files, not what language the program is written in and what its internal routines are called. I understand the docs may be written with Fortran-familiar users in mind, but it seems like these details could go in a single dedicated section called "Notes for Fortran users" or something.

The section on binary output files also mentions Fortran concepts, describes file header string lengths in Fortran syntax, and presents Fortran pseudocode for iterating cells in DISV grids. IMO the former should be replaced with more general terminology, and the latter would be easier for many people to read in Python-ish syntax (I'm not saying remove the Fortran version though).

Also, the IDM/IDP machinery does not seem like a user concern, unless MF6 at some point supports different modes of memory management, potentially conditional on how input is provided (e.g., loading a full grid-sized array into memory rather than a sparse nodelist representation), which the user must be aware of to control performance characteristics. From the user's perspective, MF6 reads input files and simulates the conditions they describe. Using the program does not require knowing which components are read using IDP vs the old way. Differences in the timing of logging output seem appropriate for release notes and/or a brief mention in the IO guide, likewise for new ways IDM allows viewing variables in memory, but I think IDM/IDP details should go in developer-facing docs.

[wpbonelli]

On the flopy4 side, there are things like

• component schema
• conceptual model
• backing data store
• netcdf concepts
• ...

It helps that we can defer to xarray and attrs for the data model/store, sort of the equivalent of IDM/P in MF6. but I'm not sure how much (re)-explanation is needed, and which details are user vs developer-facing.

Also not sure how much detail we need to go into on the relationship between DFNs and the MF6 module. Should DFNs be thought of as user-facing, or mainly for developers? Same question re: the code generation function, do we envision the user doing this at all frequently, e.g. maybe when they're switching between versions of MF6? Is that a need people often have? Presently it seems mainly developers, with most users installing the latest MF6 and corresponding flopy?

it may be tricky to find a good middle ground between too much and too little detail on all these things

[aacovski]

I support this separation. As a user, I've never touched FORTRAN and never plan to. I don't want to see anything related to the backend implementation. The last thing I want to worry about is compatibility issues between versions or understanding code. What's most important to me is how to define boundary conditions properly and making sure they're valid. Developer documents explaining implementation details should be separate, more like whitepapers for those who need that level of understanding.