search

nimbella / docs

Apache License 2.0
3 stars 9 forks source link

command list redundancy #42

Open rabbah opened 3 years ago

rabbah commented 3 years ago

there’s some redundancy between https://docs.nimbella.com/commands and https://docs.nimbella.com/command-summary.

rabbah commented 3 years ago

also Nim should be nim or Nimbella CLI in the left nav bar although the heading might just be better called Commands.

joshuaauerbachwatson commented 3 years ago

there’s some redundancy between https://docs.nimbella.com/commands and https://docs.nimbella.com/command-summary.

I noticed that. The first is stale and represents a way that first I, and then Nancy in her rewrite, thought to present the command set of nim in a more friendly way. The second is less stale (I probably should regenerate it but it's nearly correct). Also less friendly.

IMO we should, for now, connect only the command-summary to the sidebar toc. Though less friendly, it's at least complete-ish as a reference. The commands doc could be morphed into a better "overview of nim" kind of doc that does not attempt to list any commands completely (because that tends to go stale instantly).

I assume there is no invariant that says that every document in the repo has to be connected to the TOC. That would make it too hard to revise things. Once commands is detatched from the TOC, I can work on it (and other documents that represent the breakup of nim.html) to be more appropriate and the reconnect to the TOC (in a PR of course, because I suspect that the structure of the PR will be a discussion point for all of us for a long while ... it's inherently hard to get that right).

rabbah commented 3 years ago

I assume there is no invariant that says that every document in the repo has to be connected to the TOC.

There isn't. There are orphaned files (place holders now).