README refresh
Opened this issue · 5 comments
@shlevy invited me to take a look at the Scarf and Nomia READMEs. This is the first artifact to come out of that process.
Like we chatted about before, I used my own ddbeck/readme-checklist to guide changes here and I came up with this set of to-do items. I'm putting together the first companion PR to begin addressing some of these things, too.
To summarize things, we should help readers more formally identify the CLI (i.e., know what to call it, where to find it, and who made it), evaluate it (i.e., figure out if this is something for them), minimally demonstrate its ability to work, and, ideally, engage with the growing community of Scarf user-developers. It's a lot, but I've broken it down a bit.
Identify
- Pick a name and stick to it: “Scarf CLI”, “Scarf Environment Manager”, etc.
- Link to the canonical home page for the project (presumptively, this repo)
- Say something about authorship (e.g., "By the Scarf team and contributors")
Evaluate
- Provide some text that lets users understand how Scarf can help them do something. (I'm work shopping this.)
Use
- Put install instructions before usage
- Write prereqs for installation
- Write installation steps
- Write "hello world" steps
- Organize usage guide after this stuff
Engage
(We could potentially front-load this stuff, since getting people involved might be more important than getting them to use it at the moment.)
- Provide a clear CTA. The Scarf CLI is relatively new, so I expect this will be something like "File an issue" or "Fork the repo" or "Start a discussion". I expect @shlevy will have a better idea of what success looks like
Miscellany
Some other issues:
- Accessibility: The banner image has poor alt text (
./banner.png). We need to find a way to suppress the alt attribute or substitute some real alt text. - Style: there's a couple of nitpicky things in the README now (e.g., using the word "simply") that we could fix up. This might be a good point to consider choosing a Scarf-blessed style guide (e.g., using Microsoft, Google, etc. and writing down on the stuff we override).
- Organization: The current README contains some other things (Potential future tools and Supporting maintainers), which are interesting, but might be better parked elsewhere.
Thanks @ddbeck ! Do you recommend we just walk through this step by step, or have it as one big sequence of changes?
Re the name: "Scarf CLI" is the whole set of tools, "Scarf Environment Manager" is the specific sub-tool for managing environments