nushell / nushell/nushell.github.io

Add see-also section to command docs for better discoverability

Open
#1,029 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
258
Forks
561
Avg merge
3h 20m
Merged PRs (30d)
15

Description

The command docs are fantastic. I'm a new user and find myself using help foo constantly and learning a ton from the examples. However, discoverability is still an issue for me. When I realize that enter is the way to "pushd", I have no idea that shells is the way to see them (traditional "dirs"). It'd be really helpful if there was some cross-referencing in the help outputs, probably below the Examples: section.

I would be up for trying (a PR) to add a bunch of See also: sections to the commands references (.md). But want to make sure you folks are on board with the idea before putting time into it.

The motivation for this is what's seen in the Clojure docs (similar to how a single web doc resource is exported into editor tooling (cider etc)): https://clojuredocs.org/clojure.core/reduce
The "SEE ALSO" section there near the bottom (and on all the similar docs) is very useful.

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

Start by locating the command reference (.md) files and reviewing how the current help outputs present their Examples sections. Add the agreed cross-references below those examples, using the enter and shells relationship as an example. Done means the relevant command docs consistently include useful See also sections.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
40/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.