emrgnt-cmplxty/automata

Setup and Docs Need Improvement

Opened this issue · 1 comments

JustScriptin commented

The documentation lacks clear references to Python shell commands, making them particularly difficult to locate. The only shell commands I could identify were presented in the demo video, but there was no apparent flag for specifying the repository in question - just the issue number. Additionally, the setup procedure lacks a structured, step-by-step format, which leads to a significant amount of guesswork.

Improving the accessibility of the setup process could likely garner more support for this repository. Unfortunately, the current documentation is far from helpful. A worthwhile consideration might be to introduce a Docker development environment, alleviating users from grappling with OS-related issues. Alongside this, the shell commands should be well-documented and distinctions made clear between mandatory and optional elements within the .env file.

TL;DR:

  1. Enhance Documentation: Include clear references and guides for the Python shell commands in the documentation.

  2. Demo Video Improvement: In the demo video, demonstrate how to pass the repository in question along with the issue number.

  3. Structured Setup Procedure: Reformat the setup instructions into a step-by-step guide to eliminate confusion and ambiguity.

  4. Enhanced Support: Streamline the setup process to encourage more user engagement and support for the repository.

  5. Docker Development Environment: Consider introducing a Docker development environment to free users from OS-related issues. Not only as a means to run the shell. This requires adding a ".devcontainer"

  6. Command Documentation: Document the shell commands thoroughly for easy user reference.

  7. .env File Clarification: Clearly differentiate between mandatory and optional entries within the .env file in the documentation.

emrgnt-cmplxty commented
  1. Thanks for flagging this. I have updated the docs since the did appear to be stale. They are auto-generated so updating them might be tricky, but they definitely need some TLC if you would like to take a crack at it.
  2. You are right, this demo is stale - we can do much better now
    3-7. These would all be very appreciated

We have a slack channel that I would be happy to invite you on to further coordinate. Otherwise, we can just stick to this thread or Discord.

Looking forward to seeing the PR.

  • 👍1