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

Add see-also section to command docs for better discoverability #1029

Open
MicahElliott opened this issue Aug 29, 2023 · 1 comment
Open

Comments

@MicahElliott
Copy link

MicahElliott commented Aug 29, 2023

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.

@sholderbach
Copy link
Member

The command help is auto-generated from the metadata we have for the commands so this would need some extra work.

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

2 participants