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

Improve README #109

Open
mpadge opened this issue Feb 14, 2025 · 0 comments
Open

Improve README #109

mpadge opened this issue Feb 14, 2025 · 0 comments

Comments

@mpadge
Copy link
Member

mpadge commented Feb 14, 2025

From @Selbosh's review:

In the README, the statement of need should be more prominent; it's not obvious who the target audience of the package is or why the package is needed. It would be great if you could explain early on, clearly, what problem pkgmatch solves, maybe giving examples of use cases from the start

I think that you could improve the documentation by making it more self-contained and making it easier for the user to find information quickly. Some information that should be in the README is only in a vignette, and some information that should be at the start of one vignette is instead left as a link to another vignette. The dependence on LLMs is also somewhat buried: this could be a make-or-break feature for many users, but it's only mentioned at the bottom of the Installation section. I can imagine it could be a selling point that pkgmatch exploits LLMs, but it could also be a deal-breaker for some users either due to technical limitations or ethical concerns.

The package relies on ollama but it's not explained in the README what this is or why the package should depend on it, or whether you can use some functions without it. There is a function called ollama_check() that ostensibly checks for and installs ollama: add this to the README, as it seems like the first thing you would want to run after loading the package! "Procedures for setting that up are described in a separate vignette" is not super helpful without a direct link to or giving the name of said vignette! Ideally I'd put much of this information in the README, because it could be a decider on whether somebody can/will install the package in the first place. Given we are talking about local LLMs here, not everybody will know what their computational demands are, so it would be helpful to give some general indication of system requirements in the 'Before you begin' vignette and maybe in the README.

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

No branches or pull requests

1 participant