Dropdown for doc on main page

[NotTheDr01ds]

Floating an idea ...

"Ref" is just too short and ambiguous to describe the "Language Reference Guide" on the main page navbar.

What about grouping the "Documentation" together into its own dropdown? This allows us to provide a full and descriptive name for each doc link.

[NotTheDr01ds]

Note - I haven't done this for the other language translations since they don't have the Command Reference nor the Language Reference Guide (yet). For now, I'd recommend leaving those as-is.

[NotTheDr01ds]

@fdncred @sholderbach @hustcer

Thoughts?

[fdncred]

I'm on the fence about it. I kind of like what we have but could be convinced to try a menu too.

[NotTheDr01ds]

I'd be okay if we had more space to fit something other than "Ref" ;-)

[hustcer]

How about change it to:

- Book
- Commands
- Blog
- Others
     - Contrib
     - Cookbook
     - Ref

?

[NotTheDr01ds]

@hustcer It sounds like you want to keep the Book and Commands at the top level.

I kind of understand the Book link as a "Getting Started" top-level (and some more thoughts on that below), but I'm not sure that I understand wanting the Commands to be top-level? As someone who accesses the Commands reference at least once-a-day myself, I think having it behind the hover-dropdown is still really convenient.

Comparing other shells' and programming languages' top-level links

• Rust

  

• Python

  

• Go

  

• Fish

  

• Zsh

  

• Xonsh

  

• Elvish

  

None of these put any actual documentation, other than install, at the top-level. Even "The Book" for Rust is on a separate page.

Let me know your thoughts, but I consider:

• The primary purpose of the main page to be the best introduction possible for potential new users who are interested in learning about Nushell.
• An important secondary purpose is to have quick-access to important information for established users.

As such, I'd propose:

- Get Nu!
- Getting Started
- Documentation
     - The Nushell Book
     - Command Reference
     - Cookbook
     - Language Reference Guide
     - Contributing Guide
- Blog

Thoughts:

• The "Get Nu!" could also be called "Install" - Either way, I think it's important that this be a top-level link. It's position left-to-right isn't all that important, I don't believe.

  This would link to the Book chapter on Installation. I'd like to move that Chapter out of "Getting Started" and up to its own top-level chapter right after "Introduction" in the Book.

  Bonus: It still links to the Book, just a specific chapter.

  And yes, we have a brief section if you scroll down on how to "Get Nu", but IMHO this isn't visible enough. It also focuses on a bit of an odd "subset" of the installation methods. Nix, for example, is usually a few weeks behind on updating (even in Unstable) to the latest release. The latest Stable is 0.93.

• The Book's "Getting Started" and subchapter "Quick Tour" are great (kudos to whoever wrote that). It hits just the right set of topics to get a new user introduced to Nushell. Putting it as a navbar top-level link would also jump someone into the book, but at the point where it most benefits new users.

Side-Note: I get that we're trying to style ourself after the "Book" in Rust, but even that isn't titled "The Book". It's "The Rust Programming Language" there. I think it's better to be explicit in the link/title, but then we can (as with Rust) informally refer to it as the Book. I'm probably treading on some "convention" that folks might be loathe to break, but I'm hoping "The Nushell Book" is a good middle-ground. We could always leave it "Book" in the link, but I'm just floating something more descriptive, especially (again) for new users who might not have the Rust background to appreciate the reference.

[hustcer]

@NotTheDr01ds Thanks for the detailed explanation, I'm not very good at this, and these changes are acceptable to me, so it's better to see what everyone else has to say about it

[fdncred]

IMO, it's just software. If we don't like it, we can revert/change it. I'd vote to land it and see how we like it.

[NotTheDr01ds]

@hustcer No worries - I won't claim to be an expert here either, but I'm happy to help with some ideas and research.

@fdncred Agreed, but given our discussion during the weekly, I'll try to find a spot for "This week in Nu" before bringing this out of draft. I have one other related update I need to push first, then I'll come back to this one.

[NotTheDr01ds]

Alright - I've added a link to "This Week in Nu". This probably means moving the Blog and ThisWeek under a dropdown for "News".

I'd love to keep the Blog at the top level, but grouping it with ThisWeek seemed the best fit. Open to other ideas, though.

@fdncred Up to you on whether you want to land it as suggested above or perhaps wait 24 hours for any feedback on the latest.

[fdncred]

Seems like we wouldn't want to update the docs every week to point at this week's specific TWiN. Maybe it's better to point to a folder with all of the list by date in reverse?

[NotTheDr01ds]

cc: @rgwood

Seems like we wouldn't want to update the docs every week to point at this week's specific TWiN. Maybe it's better to point to a folder with all of the list by date in reverse?

Right - I guess I should have gone into more detail on the issues and possible solutions here.

I'd love to be able to point to something static (eventually), but that's going to require some other changes. For now, I chose to link to the latest, and then once we come up with a better solution we can link to the static page.

So right now, "This Week in Nu" is, of course, a separate repo. All of the weekly files are simply tossed in the root of that repo, and given the numbering system, the only sorting possible is alphabetical.

I spent a few minutes looking at having a make_twin.nu script that would read the repo, find the latest add, and update the link to that. But that's still a weekly, manual process. Perhaps it could be automated through a GitHub action - not sure.

I'm thinking maybe the solution is to have some statically named file that represents this week's TWiN, perhaps the README.md in the repo. Each week, the latest update could simply be the README.md, with the link hardcoded to that (and never changing). Then on the subsequent week, README.md is renamed to "This week in Nu [nnn].md" and the new README.md is created.

Ideas welcome here.

[NotTheDr01ds]

@rgwood Btw, in case no one mentioned it, during yesterday's weekly, someone brought up the idea of using This Week in Nu to potentially highlight some of the community work like Maxim's YouTube videos (after review). I mentioned that there was currently no link (that I'm aware of) from the main page or doc to TWiN, and everyone was in strong agreement that we should add a link so that your work is more prominent.

That's what I'm attempting to address in these latest commits.

[rgwood]

Thanks for the context. I won't have time to work on this anytime soon, but yeah if we could automate something to have a static link to the latest TWiN that would be great.

[fdncred]

We could also just move the TWiN into this repo if that makes it easier to put in the docs. We'd need to get some consensus though.

[rgwood]

I don't feel strongly about where it lives; as long as the process of uploading it to GitHub stays easy, any repo is fine.

[NotTheDr01ds]

We could also just move the TWiN into this repo if that makes it easier to put in the docs

The big advantage to having it in the repo directly would be that we could serve it through VuePress (or successor) and it can be formatted more nicely than just displaying it in the GitHub UI. It can also pick up things like ::: warning tags, etc.

Either way, though, it's going to require some automation in order to get a static link.

In the meantime, we have two options, I believe:

• Update manually every week
• Take out the link for now and revisit this when we move things over later

Which way do we want to go? I think that's the one remaining thing to lock down before this lands?

[fdncred]

I don't want to put more burning on Reilly or his fill-in to update another thing for TWiN. So, my suggestion would be to leave it out now until we have a good, automated solution. I'd like to list them all by date with the most recent on top.

[NotTheDr01ds]

Ok, I've dropped the link to TWiN and reverted "Blog" to the top level. Should be good to land based on previous comments.

[fdncred]

Let's try it out

[fdncred]

nice!