Add a template for MPAS-Ocean design docs

[xylar]

This merge adds a template RestructuredText document that can be used for future design documents for MPAS-Ocean. Design docs that follow this template should be easier to incorporate into the documentation we plan to build.

[xylar]

@mark-petersen and @vanroekel, this template has made its way back to MPAS-Model via MPAS-Analysis and compass. It's a little stale but mostly still applies. Feel free to suggest edits. We can merge this whenever there's a convenient window for such non-code changes.

[mgduda]

Is there an argument for placing design documents in the MPAS-Model repository rather than the MPAS-Documents repository?

[xylar]

@mgduda, yes, I think we want design documents to be part of the documentation generated by CI. I don't think MPAS-Ocean will be using MPAS-Documents at all anymore. We want to keep the documentation in better sync with the model itself and have CI update it with each PR.

[mgduda]

Sorry for asking what might be clueless questions -- I feel like I'm somewhat in the dark, here -- but is it likely that we'll be adding binary files (plots, other figures, PDF versions of documents, etc.) to the MPAS-Model repository? If so, perhaps a broader discussion might be in order.

[xylar]

@mgduda, I would think these concerns are general to having documentation in MPAS-Model, and not anything specifically to do with design documents, right?

I wouldn't anticipate pdfs, large images, figures or plots being part of design documents or any other documentation. In all of the other MPAS-Dev repos where I have added documentation, I do include small PNG files (these could be JPEGs if space is a concern), sometimes for illustrative purposes, sometimes just to make things a bit more visually interesting. I certainly wouldn't anticipate these images contributing an appreciable amount to the size of the repo or its history. But I could understand that being a concern.

This does seem like it would be worth a discussion. I guess this PR is as good a place as any...

[xylar]

@cbegeman, if you have feedback on the template as you go through writing your design doc in #763, that would be very helpful. Feel free to suggest modifications using the "suggest" button after highlighting the lines you would like to change. This is similar to what I did on your PR.

[cbegeman]

@xylar Should the Design solution section be moved to Design and Implementation? Couldn't quite figure out how to formally "suggest" this.

[xylar]

I agree, this should change. Whoever originally designed this template used this naming convention and I agree it's confusing. I think Implementation is the correct name in the next section. So the sections should instead presumably be Algorithm Design (which could be the section and the subsection both) and Implementation (again, section and subsection). Does that make sense to you?

[cbegeman]

Yes, that sounds appropriate to me.

[xylar]

By the way, you're right. "suggest" only helps when you're making minor tweaks to the text, not moving sections and such.

[xylar]

@cbegeman, let me know if the latest changes seem sufficient to address your suggested changes.

[mark-petersen]

This looks perfect, thanks! I did a quick test compile, and everything worked. I'll merge this in when I can.

[cbegeman]

@cbegeman, let me know if the latest changes seem sufficient to address your suggested changes.

It looks good, thanks. My only question is whether the algorithm design section should still be optional.

[xylar]

My only question is whether the algorithm design section should still be optional.

I think so. It sometimes makes sense to retroactively put together a design for something that's already implemented. In such cases, we usually just do the other 3 sections and leave out the algorithms (essentially consolidating them into the description of the implementation). But I'm open to requiring they be kept separate.

[xylar]

@mark-petersen, thanks for the review. Let's wait until @vanroekel has had a chance to review before merging.

[vanroekel]

Sorry @xylar for letting this one slip. I thought I had reviewed this one but mixed it up with the compass design doc. I think this looks great, I just had a couple questions for my own clarification

1. In this text based format for design docs are there methods to put in typeset equations (e.g. LaTex)? I find that especially helpful in algorithmic design sections and for comparison to the implementation. I worry about trying to understand the design doc if we just look at the text file
2. What is the process for adding images? There are times when a schematic can prove useful as well.

[mark-petersen]

Good point. Would be nice to have some example lines of both in the template.

[xylar]

@vanroekel and @mark-petersen, I added examples of both math and images. Both are easy to handle. @mgduda expressed concern about images above (presumably because we don't want binary files becoming an appreciable fraction of the total size of the MPAS-Model repo when it gets cloned). I have tried to impress this on folks making design docs with the text I added.

Let me know if your concerns are addressed. Keep in mind that I don't want to use the template as a general tutorial on RestructureText, especially because the whole documentation will hopefully soon be written in this way as it is for MPAS-Analysis, pyremap, geometric_features, compass and MPAS-Tools.

[vanroekel]

Thanks @xylar these changes are great and way more than I was expecting. I was really just curious if it was possible to add equations/images, sorry if that wasn't clear. I also agree with you this isn't the place for a full design docs tutorial.