Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reorganize README #265

Closed
3 tasks done
chrispcampbell opened this issue Oct 24, 2022 · 2 comments · Fixed by #333
Closed
3 tasks done

Reorganize README #265

chrispcampbell opened this issue Oct 24, 2022 · 2 comments · Fixed by #333

Comments

@chrispcampbell
Copy link
Contributor

chrispcampbell commented Oct 24, 2022

The current README is very thorough, but it contains a mix of user-facing (installation, usage) and developer-facing (debugging, architectural) documentation, so it may be overwhelming to new users. Both kinds of documentation are important, but I think it would be better to have the succinct user-facing docs in the README, and move the developer-facing docs to the wiki or a separate docs folder.

Additionally, all the new packages that have been added in recent months haven't yet been mentioned in the README, mostly because I've been waiting to revisit how the README is organized.

For the new README, I propose the following structure:

  • Intro
  • Caveats
  • Quick Start (npm create @sdeverywhere)
  • Packages (table of @sdeverywhere packages, with links to docs+changelog for each)
  • Installation and Usage
    • Using SDE to build a web app (high-level)
    • Using SDE to generate C code (low-level)
  • Supported Functions (list of Vensim functions supported by SDE, with caveats noted)

As part of this, I will need to revisit the "Using SDEverywhere to Make a Vensim Model into a Web Application" document and update it to account for the new build/plugin system, or just fold the changes into the README.

Checklist of things to resolve as part of this work:

  • Revisit "Using SDEverywhere to Make a Vensim Model into a Web Application" document
  • Include note about DEPRECIATE STRAIGHTLINE fiscal period argument being unsupported (see feat: implement DEPRECIATE STRAIGHTLINE #264 (review))
  • Change Quick Start instructions to suggest cd to a directory containing an mdl file
@ToddFincannonEI
Copy link
Collaborator

Yes, I think this is long overdue. Would you like me to move the rest of the README into wiki pages? I would split it up into multiple pages.

@chrispcampbell
Copy link
Contributor Author

@ToddFincannonEI: I started working on the reorg already, so I can take care of it. My plan was to move the developer and architecture parts into separate md files in the docs directory for now to make the review easier (so that you can see where things were moved to all at once). Once I submit the PR, we can decide whether those should live in the repo (in docs directory) or in the wiki.

FWIW, I like using the wiki for things like architecture that are less likely to change over time and that aren't tightly bound to a current revision of the repo. Also, it's easier to make quick edits to the wiki. For things like developer guides or API docs that refer to a specific (current) revision of the repo, sometimes a docs directory is better so that there's less chance of confusion (assuming it stays up to date with the rest of the repo). But, for our purposes, as long as we keep the docs updated to reflect the latest state of the repo (main branch), it's probably fine to use the wiki. So that's my thought process, and it sounds like I've convinced myself that wiki is the way to go for those portions of the docs :) Let's discuss one more time when I submit the PR in the next day or two.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants