[STORY] Polish the initial impression of running meeshkan

[fornwall]

This is a collection of tasks that can be done for improving the initial impressions of running meeshkan.

Some possible ones:

• Make it possible to install meeshkan using homebrew (Add homebrew instructions to README #120).
• Make it possible to install meeshkan using apt on Debian and Ubuntu (Add Debian and Ubuntu installation instructions #137).
• Look at the output of meeshkan --help and meeshkan CMD --help and see if things can be improved (Improve --help output #124).
• Shorten the log format (Shorten log format #126).
• Add colors to the logging.
• Add emojis to the logging (some added in Log endpoints at startup #142, more can be added).
• Ensuring that we don't forget about user experience, perhaps by adding PR template with notes about the docs.

For meeshkan record:

• Some questions that came up for me: If I already have a jsonl file and I go back to record more, does it update or overwrite? Is there any way to overwrite a specific file without deleting and regenerating? These questions could be solved via documentation or code, depending on how the product acts now.
• One of the first logs says when running says spec generation mode disabled and I was like uhhhh what is this, is it bad 😆 Could be good to clarify for users what this means.
• It currently doesn't tell you that it has created two directories (logs and specs)
• Once the initial logs have printed, that's it. There's no helpful logs to reassure you that it's doing anything.
• If you're using curl or another command-line tool to make requests, it should be done in a separate window because Meeshkan record is a blocking process. We don't mention this anywhere, so it's hard to know that this is what you're supposed to do. (Documented with Docs: Polish initial impression of running Meeshkan #144)
• How many API calls are "enough"? For the tutorial, we do 33 requests to the Pokemon API - but in general we haven't stress tested this. Is it just the more calls, the more accurate? Or is there a minimum number of calls? Would be good to know.
• How do you kill the recorder without losing data? Turns out you do ctrl + c or a kill command - but that's not written anywhere. It'd be nice to have that documented or, even better, have a stop command (Documented in Docs: Polish initial impression of running Meeshkan #144, but still in favor of a stop command)
• Update documentation to reflect recordings filename changes in Update recordings filename. #100 in both RECORD.md and BUILD.md (Docs: Polish initial impression of running Meeshkan #144)
• Continuously build a schema when recording, and print a line every time the schema is updated due to a recording. That would give an indication when updates are slowing down/stopping, so the further recordings are not needed.

For meeshkan build:

• Update documentation to default build output changes in Change default build to specs. #99 (Docs: Polish initial impression of running Meeshkan #144)
• Better flag descriptions in BUILD.md (ie the differences between using -o and -a) (Docs: Polish initial impression of running Meeshkan #144)

For meeshkan mock:

• Explain what the -s flag is doing in mock command example in MOCK.md (In meeshkan/meeshkan@608524e we write out --specs-dir)
• When creating my mock server, I needed to search for the servers field in OpenAPI spec to find the URL for the mock server to respond to. But I only knew to do that because Mike told me to. We should clarify in docs that this is located there and that it will usually be the same url as the API itself, unless you hack it. We haven’t mentioned hackability much in the existing documentation. If we write out the endpoints at startup, then this is less of a problem. See also the next note about logging endpoints at startup. Solved by Log endpoints at startup #142.
• Log the endpoints at startup ala https://github.com/stoplightio/prism (gif) (Log endpoints at startup #142)
• We are currently using http://localhost:9000/http://myapi.com/path/to/api, perhaps use http://localhost:9000/path/to/api without the host (that's what prism and mocklab does at least).
• How do we know that it’s not calling the real API? The host URL is the same. Mock mode never calls the real API - should be specified.
• Clarify that the default value that the mock command will search in is specs. Or remove the default completely (Removed default in Simplify and enhance mock specs handling #154)
• It should validate the input --> if it’s an int and you put in a string, we should show an error (Validate mock input data #138).
• Remove --specs-dir as an option, and instead take it as an argument. So run it like meeshkan mock directory instead of meeshkan mock --specs-dir directory (Simplify and enhance mock specs handling #154) (documented in Docs: Polish initial impression of running Meeshkan #144)
• Support running on a single schema file as well, like in meeshkan mock file-or-directory (Simplify and enhance mock specs handling #154)

General documentation improvements:

• Should we recommend that people run a virtual environment? I've always had a better time when I've used one and we recommend it in many of our tutorials.
• Link to instructions for installing curl, postman, etc (Docs: Polish initial impression of running Meeshkan #144)
• Explain what a daemon is once the quick start demo is ready (quick start demo isn't there, but the general issue is solved by linking daemon docs in Docs: Polish initial impression of running Meeshkan #144)
• Links to the next section at the end of each docs page (ie if you're currently on the recording docs, a link to the build docs) (Docs: Polish initial impression of running Meeshkan #144)
• At the end of each section of the README, instead of a sentence explaining what the documentation has in it --> have a list
• Always write out the long format of options (like --admin-port instead of -a) in documentation (Docs: Polish initial impression of running Meeshkan #144)
• Add a shell completion to the install.
• Write a link to the README in the --help output.

When working on this, let's create links to PR:s and concrete issues to visualise what has been done and ideas for further improvements.

[carolstran]

Added a bunch of suggestions under four different categories: For meeshkan record, For meeshkan build, For meeshkan mock and General documentation improvements.

There are still two bugs that I need to file which will also potentially inform this list. One is related the differences between build modes (gen and replay) and the other is related to meeshkan record recognizing integers in query params.

[fornwall]

Things to discuss:

• Should we have schema generation in the record command (Should meeshkan record have --specs-dir and --mode options? #123)? It might complicate things for users.
• One sentence elevator pitch and should we focus more on the mocking part (Improve on our elevator pitch (one sentence summary) #121)
• Why do we have header based routing (used in tutorial) (Document a use case of or drop header based routing in the mock command #122).