Make plugin creation documentation language more precise
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 25.6k
- Forks
- 941
- Avg merge
- 9h 24m
- Merged PRs (30d)
- 3
Description
### How can we improve the documentation?
On https://github.com/asdf-vm/asdf/pull/1445 I noted a number of small things that could be changed to make the plugin creation documentation more **precise**. Enumerating them:
* **Update the document so that it is clear "plugin scripts" are specifically callbacks that will be invoked at the right time by asdf**. It might be good to emphasizing this somewhere here at the top of the document for clarity. These are "callback scripts invoked by asdf when needed".
* **_"The full list of Environment Variables used throughout all scripts."_ seems at odds with _"Not all environment variables are available in all scripts."_.** Reword or combine these lines for clarity
* **Update the doc so the word "parameters" is used represent values a script or function accepts as input, and "arguments" for values that get passed to a script or function when it's invoked**. See https://stackoverflow.com/questions/156767/whats-the-difference-between-an-argument-and-a-parameter
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Locate the plugin creation documentation discussed in pull request 1445 and review the three wording issues listed here. Clarify that plugin scripts are callbacks invoked by asdf, reconcile the environment-variable statements, and distinguish parameters from arguments. Done means all three points are addressed clearly in the documentation.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100