Improve local-repo docs

[axelson]

From my initial reading of the docs (as a relative straight.el newbie) I didn't realize that local-repo was meant for working with files on the local file system, I assumed that it was something that you would use with your own git repository server.

I hope that by being more specific about what a "local repository" is that it will be easier for others to understand how to use the option.

I hope my understanding of what local-repo does is good, if not then hopefully we can still improve the wording while remaining accurate.

[progfolio]

Not sure about the phrases "git directory" and "plain directory" here.
A "git directory", if I understand your intention, is just a repository.
A "plain directory" is just a directory. Those terms would probably be better. Keep in mind that other version control back ends may be implemented, so it's best to avoid referring to git directly when it's unnecessary.

[axelson]

I got tripped up initially because repository can mean many different things in computer science so when I was initially reading through the list of options I wasn't sure what repository meant in this context.

Maybe this would be more straightforward: "This is the path to a local vcs repository (git by default)"

Although since with :type nil it doesn't have to actually be a vcs repository so maybe something could be added to that effect.

[progfolio]

The text you added above mentions that :local-repo may be a local repository or directory, but the example is referring directly to an elisp file. Unless the directory is named "example.el", in which case the file path should end in a forward slash. It would be better to pick a name for the directory which didn't include the ".el" extension to avoid confusion, too.

Does this example work if you run it?

[axelson]

Yeah I intended it to be a directory named example.el, but I agree that is confusing. I haven't run straight.el stand-alone so I'm not 100% sure this example would work on it's own.

[progfolio]

Apologies for the confusion. The documentation could use an overhaul in general (see #671).
While the current README is thorough, I feel it misses what many users are actually looking for: "How do I do X with straight?"
Ideally, what you're referring to here would fall under "How do I manage locally hosted elisp with straight.el?"

You have the right idea. You'll want to point the :local-repo at the directory containing the elisp.
If that directory is not under version control, you would want to add :type nil to prevent straight from attempting to manage it as if it were under version control. To add to your example:

(straight-use-package '(my-local-package :local-repo "/path/to/my-local-package/" :type nil) ;;directory not under version control

Until the new documentation is written, we would probably be better to adding this use-case to the FAQ.
Does that work for you?

[axelson]

I think that a workflow-based section of the README would be helpful, although I don't think it would supplant the reference portion (although perhaps the reference portion could shrink a bit).

I don't think I would have noticed this if it was in the FAQ unless it showed up when I did ctrl-f but I'm not entirely sure what the best keywords for that would be. I think I missed the FAQ completely when I was initially looking, including the FAQ link at the very top of the README. One issue with the FAQ as it stands is that in order to see the index of questions in the FAQ you need to scroll down 3 full pages. One way to help that would be to insert a table of contents at the beginning of the FAQ section although that might be a maintenance burden to keep up to date.

Another idea could be to tidy up the Getting Started section and link a few workflows (in the FAQ) from there.