Proposal: store technical documents in InVEST

[dcdenu4]

Background

This is a co-sponsored proposal between @dcdenu4 and @phargogh that came from a chat about whether the SDR LS factor rework warranted a PEP.

Problem

Given the scientific nature of our software there are times when we need to update an equation, rework an algorithm, or make some kind of non-trivial change to a model. These changes often don't require full PEP write ups and the discussion and reasoning behind the changes don't fully get captured in related issues, PR descriptions, history notes, or the Users Guide. This often leads to that historical knowledge being confined to the modeler and software engineer who made the changes. This causes future us to try and decipher why certain changes were made and what the reasoning behind them was.

Suggested solution

When a non-trivial InVEST model change is needed, a write up of that change and decision should be stored in the InVEST repository so that it can be referenced in the future. GDAL does something similar with a doc/source/development/rfc structure that we could take inspiration from.

Scope of work

This is proposal is for adopting a new software team practice and does not require any development time.

[dcdenu4]

@phargogh, please feel free to add to this or rework it!

[phargogh]

Storing these decisions and some related discussion in the InVEST repository also means that their contents will be ported with the repository wherever it goes ... which is likely to have greater longevity than having something in an issue tracker if we needed to move to a new source control host with a different issue tracker data structure.

@dcdenu4 I just realized that it might also be helpful for us to think through some suggestions for when this kind of documentation would be useful.

For science things (like the SDR issue), maybe whenever the issue is a "major" change to functionality where it feels like we'll need to answer questions about what changed and why?

I'm not yet sure if there's a technical need at the moment that isn't science related, so maybe we can punt on that for a bit?