docs: reorganize README with emphasis on end user documentation

[chrispcampbell]

Fixes #265

Summary of changes:

• Rewrote the top-level README to cover newer functionality that has been added in the past couple years (model check tools, local dev environment, the create script, etc).
• Added screenshots and videos.
• Moved the more technical developer/contributor-focused documentation from the top-level README to a new section for contributors in the wiki.
• Moved the detailed sde command reference to the cli package README.
• Removed the documentation files that were previously in the notes directory; these have been migrated to the wiki. (I haven't finished rewriting the "making a web app" guide, but there's a placeholder on the wiki that should be OK for now and I'll finish fleshing that page out after this gets merged.)
• Added consistent sections (Quick Start, Install, Usage, Documentation) to the READMEs for individual packages.

See the rendered README for this branch here (i.e., what the landing page will look like after this branch is merged):
https://github.com/climateinteractive/SDEverywhere/blob/chris/265-readme/README.md

[ToddFincannonEI]

I love the new introduction. It makes me excited about using SDEverywhere. Getting something to run with one command is a much lower barrier to entry that what we had before. I like the way you separated out the more technical details into the wiki.

Here are a few questions and comments by section.

Supported Platforms

• Have we run WebAssembly on the server?

Supported File Formats

• Is there a published roadmap? We may not want to mention XMILE given the low priority in both our ourgs.
• This would be a good place to link to the supported Vensim functions in the wiki.
• It would be helpful to document someplace (probably not here) the compiler error you get when using an unsupported Vensim function. This seems to surprise people, and it looks like SDEverywhere generated bad code. Maybe just issue an SDEverywhere compiler message instead.

Features

• Live editing and quality checks and comparisons might be our killer feature, since your tools do this better than the vendor tools. Maybe mention it up higher.

SDEverywhere in Production

• You could add EPS to the production apps. Energy Policy Simulator

Contributing

• We fully handle :EXCEPT: clauses now.
• Should we mention antlr4-vensim?

[chrispcampbell]

@ToddFincannonEI: Thanks for the review and ideas. I pushed a bunch of commits to address your feedback, and comments are inline below. I'll merge this PR shortly and we can continue to improve the README as things come up.

I love the new introduction. It makes me excited about using SDEverywhere. Getting something to run with one command is a much lower barrier to entry that what we had before. I like the way you separated out the more technical details into the wiki.

Great!

Supported Platforms

• Have we run WebAssembly on the server?

Yes, the same WebAssembly blob can run in both browser and in a command-line or server-side Node application. There are examples that exercise this in a few places, for example, in the integration tests (under tests/integration, like this script). When model-check tests are run on the command line, that's another example of the WASM code running in a Node process.

Also, the En-ROADS SDK includes a simple example of running the model in a Node application. Your question makes me realize that we can include some better docs and examples for this use case; we can even make the create script auto-generate a small Node script that runs the model in addition to the web app we already generate. I'll add it to my list.

Supported File Formats

• Is there a published roadmap? We may not want to mention XMILE given the low priority in both our ourgs.

The only roadmap at this point is this post I wrote up on the discussion board, along with the roadmap that's in my head. I was on the fence about mentioning XMILE for the reason you mention, but thought it might be worth mentioning in case anyone is inspired to help make it a reality.

I changed it to not say "roadmap"; instead it now says that it's not currently supported but is something we'd like to see if anyone wants to help.

• This would be a good place to link to the supported Vensim functions in the wiki.

Good idea. Link added.

• It would be helpful to document someplace (probably not here) the compiler error you get when using an unsupported Vensim function. This seems to surprise people, and it looks like SDEverywhere generated bad code. Maybe just issue an SDEverywhere compiler message instead.

Yeah, in the short term we can document this, but I think ideally it would be better if the SDE compiler would fail fast and emit a more useful error message in this case. I'll file an issue this week.

Features

• Live editing and quality checks and comparisons might be our killer feature, since your tools do this better than the vendor tools. Maybe mention it up higher.

Yeah, I wasn't sure the best place for the Features section (since it's a little wordy), but having it up higher makes sense. I've moved it up to be between "Supported File Formats" and "Core Functionality".

SDEverywhere in Production

• You could add EPS to the production apps. Energy Policy Simulator

Great, I meant to ask you directly if it would be OK to include EPS. I've added a bullet. Let me know if you'd like to change the wording.

Contributing

• We fully handle :EXCEPT: clauses now.

Good catch, I removed mention of EXCEPT clauses.

• Should we mention antlr4-vensim?

Sounds good, I added a link to the first bullet about improving the parser.