asdf-vm / asdf-vm/asdf

Make plugin creation documentation language more precise

Open
#1,595 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.