Provide user-friendly templates for design documents

[pwolfram]

Each new analysis is expected to have a well formulated design document that can be reviewed when the project is complete. As such, a template for the design document should be provided.

[pwolfram]

@milenaveneziani and @xylar, we don't seem to be following this original requirement. So far I don't think this is a huge problem because the analysis added haven't been too terribly complex. However, it may be worth it to corporately

1. recognize that we aren't meeting this requirement
2. decide to either be ok with that are enforce the requirement, on a case by case basis

If we are not ok with 2, then we should probably have a plan to fix this issue in our roadmap.

[xylar]

I think we should require this from now on. I think the default should be to use the existing confluence template, but we can provide a template specific to Analysis if we think there are useful differences from existing template. Off the top of my head, I don't see any.

[xylar]

As far as I'm aware, the only major additions to the Analysis since we moved to this repo have been:

• nearest-neighbor interpolation
• SSS
• MLD

In retrospect, I would have liked to have design documents in each of those cases but it hasn't been a big deal so far.

I think we do want to have design documents for MOC (probably separately for global and regional), NINO3.4, etc. and also for any new modules (e.g. interpolation, plotting) that we either create from scratch or pull out of existing analysis functions.

[pwolfram]

@xylar, I think the primary purpose of design documents is to verify that the proposed implementation meets group goals. Existing codes that don't have design documents, for example, have essentially already been ratified and I would argue have minimal value-added for the design document as a consequence, provided the code itself is relatively clear and straightforward. Also, I think that design documents should be stored in this repo once ratified via confluence. At this point, however, I'm not sure we can fully operate under this more robust set of procedures because participation is currently too low. However, I agree that it is best practices to have design documents and as long as we can make them simple, clear and easy we are likely to get wider participation and usage.

[xylar]

@pwolfram, you're right. I wasn't suggesting that we retroactively create design docs for things we've already done.

I agree that it's a good idea to create a subdirectory in the repo where we put completed design docs.

I agree with your principle on design docs. I don't think you answered the question though, which was whether you think the existing template on confluence needs to be modified in ways that are specific to Analysis or if the existing template is good enough.

[pwolfram]

@xylar, I recommend we use strictly markdown following https://acme-climate.atlassian.net/wiki/display/OCNICE/Design+Document+Template as specified in #87 with a form of

Title: Some descriptive title
ACME Ocean and Ice Team
date: x - xx - xxxx

Summary

The purpose of this section is to summarize what capability is to be added to the ACME Ocean and Ice system through this design process. It should be clear what new code will do that the current code does not. Summarizing the primary challenges with respect to software design and implementation is also appropriate for th is section. Finally, this statement should contain general statement with regard to what is “success.”

Requirements

Requirement: name-of-requirement-here
Date last modified: 2011/01/05
Contributors: (add your name to this list if it does not appear)

Each requirement is to be listed under a ”section” heading, as there will be a one-to-one correspondence between requirements, design, proposed imple- mentation
and testing. Requirements should not discuss technical software issues, but rather focus on model capability. To the extent possible, require- ments should be re
latively independent of each other, thus allowing a clean design solution, implementation and testing plan.

Algorithmic Formulations

Design solution: short-description-of-proposed-solution-here
Date last modified: 2011/01/05
Contributors: (add your name to this list if it does not appear)

For each requirement, there is a design solution that is intended to meet that requirement. Design solutions can include detailed technical discussions of PDEs,
algorithms, solvers and similar, as well as technical discussion of performance issues. In general, this section should steer away from a detailed discussion of
low-level software issues such as variable declarations, interfaces and sequencing.

Design and Implementation

Implementation: short-desciption-of-implementation-here
Date last modified: 2011/01/05
Contributors: (add your name to this list if it does not appear)

This section should detail the plan for implementing the design solution for requirement XXX. In general, this section is software-centric with a focus on softwa
re implementation. Pseudo code is appropriate in this section. Links to actual source code are appropriate. Project management items, such as svn branches, timel
ines and staffing are also appropriate. How do we typeset pseudo code?

Testing

Testing and Validation: short-desciption-of-testing-here
Date last modified: 2011/01/05
Contributors: (add your name to this list if it does not appear)

How will XXX be tested? i.e. how will be we know when we have met requirement XXX. Will these unit tests be included in the ongoing going forward?

[pwolfram]

I think we should be able to close this issue following merge of #87.

[milenaveneziani]

I am afraid that requiring design documents for any analysis code will greatly reduce the already low level of participation.
At least, I'd say let us make it simpler: for example, the algorithm will probably be easy in most cases. Could we just have Design and Implementation, in which one could include a brief description of the algorithm at the top?

[pwolfram]

Bumping this discussion to #87....

[xylar]

I think we're now meeting this requirement (depending on your definition of "user friendly").