Documentation Feedback

[TimUntersberger]

I am currently not very happy with the structure of the documentation, but I don't really know how to improve it.

I'd appreciate any kind of feedback regarding this.

[keepitsane]

Development build documentation has a missing semicolon for bar and workspace settings. Also the font setting under bar now needs to be enclosed in quotes, when in ymal it didn't need to be.

[TimUntersberger]

Development build documentation has a missing semicolon for bar and workspace settings

Added.

Also the font setting under bar now needs to be enclosed in quotes, when in ymal it didn't need to be

That's just the difference in file formats. Because rhai is a real programming language and not something as simple as yaml, you now need to specifiy when something is a string.

[keepitsane]

Got it that makes sense. Just figured I would mention it as it might cause confusion as people migrate from yaml to rhai as it wasn't mentioned in the new docs.

[ramirezmike]

What exactly is it that makes you not happy about the documentation? Is it the organization of the content in the readme or the wording? Is it the amount of content? Should parts be moved to the wiki?

I did think with the improvements you've made to the configs along with the list of modular features you've added it might be good to have somewhere that lists custom configs from users.

[TimUntersberger]

Reading the documentation is very inconvenient. The readme has gotten so long, that you have to scroll a lot to go to the parts you are looking for. The style is inconsistent, the structure could be better and there could be a lot more documentation.

Writing the documentation is also very cumbersome, because everything lives in one big file. I will probably move the documentation from the README to a wiki or even into a website (might be overkill).

I did think with the improvements you've made to the configs along with the list of modular features you've added it might be good to have somewhere that lists custom configs from users.

That's a good suggestion!

[TimUntersberger]

I am currently rewriting the documentation and I would really appreciate it if some of you would read the new documentation and give me some feedback. https://timuntersberger.github.io/nog

[ramirezmike]

I like it so far just needs more content filled out, I think. It'd be nice if there were more example images and gifs on the front page showing maybe other applications too. Maybe also a short blurb on what a tiling window manager is and what existing/planned features nog has (maybe could be just a link to a filtered list of the github issues)?

[keepitsane]

Yeah looking good so far, I agree with ramiezmike about more images and gifs. Maybe each settings can have a gif demonstrating what it actually does. Also font size could be increased by a point or two imo.

[ramirezmike]

import 'nog/components' as C;

in the bar config doesn't work I think because it's expecting single quote to be a character.

Also, not sure if it's because of my branch switching but once I got to the point where I was using these .nog configs locally the default script that generated just gave me a blank app_bar... but I think the config you have here works fine.

[TimUntersberger]

import 'nog/components' as C;

Yeah sorry you need to use " instead.

[TimUntersberger]

Also, not sure if it's because of my branch switching but once I got to the point where I was using these .nog configs locally the default script that generated just gave me a blank app_bar... but I think the config you have here works fine.

That's because currrently there isn't really a default combination of components. I am going to add one today.

[ramirezmike]

The preview video is neat but what is the thing you use to open programs? Because A) I want that and B) it's not clear that it's not part of nog?

Also, I noticed on my phone at least when switching pages using the menu it retains the scroll of the page I left. So, sometimes it will load the next page but already be scrolled down half the page.

Also, maybe there should be some information about the tray icon and how it has the ability to reload nog + a suggestion to use it if the user runs into an issue as a way to resolve it without losing their setup.

[TimUntersberger]

The preview video is neat but what is the thing you use to open programs? Because A) I want that and B) it's not clear that it's not part of nog?

https://timuntersberger.github.io/nog/#/configuration/keybindings?id=launch

Also, maybe there should be some information about the tray icon and how it has the ability to reload nog + a suggestion to use it if the user runs into an issue as a way to resolve it without losing their setup.

👍

[ramirezmike]

The preview video is neat but what is the thing you use to open programs? Because A) I want that and B) it's not clear that it's not part of nog?

https://timuntersberger.github.io/nog/#/configuration/keybindings?id=launch

Sorry, not the launch keybinding, this thing that you're using to search and launch apps

[TimUntersberger]

https://github.com/microsoft/PowerToys/wiki/PowerToys-Run-Overview

[cristianovitorino]

• A search functionality could be really helpful. At the moment we have to remember precisely where something is in order to find it.
• A dark theme option would be nice, easier on the eyes. Specially if it's the first time you're learning the WM, you will spend quite some time looking at the docs.
• Also would be a cool initiative if there was the beginnings of documentation for contributors, project goals, how and where to focus contributions, overall planning, etc.

[ramirezmike]

looking at latest on the custom-language branch (not sure where the best place to discuss this is?)

On the functions page there's this example

var count = 0;

// This function captures a copy of count not a reference
var inc = by => {
  count += by
}

// increments a copy of count
inc(1)
// increments a copy of count
inc(1)

// Count is still 0
print(count)

Might be good to add a print statement in the function too like this to further demonstrates that the function retains its own copy across calls to it

var inc = by => {
  count += by
  print(count) // calls to inc will print out the current value
}

Using this, I was able to write this toggle which I was super excited about:

var toggle_split = false;

nog.bind("Alt+T", () => {
    if toggle_split {
        nog.workspace.set_split_direction("Vertical")
    } else {
        nog.workspace.set_split_direction("Horizontal")
    }

    toggle_split =  !toggle_split 
})

Separately, I was a little confused with the "elif" in the conditionals example:

if true {

} else true {

} elif {

}

was that intended to be "elif true"?

[TimUntersberger]

Might be good to add a print statement in the function too like this to further demonstrates that the function retains its own copy across calls to it

👍

was that intended to be "elif true"

whoops.... I swapped else with elif 😆

[TimUntersberger]

@cristianovitorino

A search functionality could be really helpful. At the moment we have to remember precisely where something is in order to find it.

I am currently rewriting the documentation using mdbook which has this and dark mode included.

Also would be a cool initiative if there was the beginnings of documentation for contributors, project goals, how and where to focus contributions, overall planning, etc.

👍

[ramirezmike]

Ah, sorry was trying to add a comment and hit the close button by accident

Was able to look over the bulk of the config changes +1

One thing I did have a question on is in the nogscript's nog API signatures, like for bind you have this (bool, callback, string)

fn bind(always_active: Boolean?, callback: (), key_combo: String) -> Void

and the example's parameter order is (string, callback)

nog.bind("F1", () => print("Hello World"))

And this is an example from your config example (string, callback, bool)

nog.bind("Alt+Control+W", nog.toggle_work_mode, true)

Am I misunderstanding the signature ordering or is it reversed?

[TimUntersberger]

@ramirezmike yeah I accidently reversed the order.

[ramirezmike]

I finally realized what my issue was with using the nog.launch binding. In the old rhai configs, I had strings with backward slash escapes

C:\\Program Files\\vim\\gvim.exe

But the new parsing crashes on the \. However it works with forward slashes

C:/Program Files/vim/gvim.exe

I don't know if it's something worth fixing but maybe we should add a note in the launch documentation instead?

[TimUntersberger]

@ramirezmike that is 100% a bug. I will fix it later this week.

[keepitsane]

Seems like the link to the documentation is currently broken.

[ramirezmike]

The functions exposed on nog.window and nog.workspace seem to be missing from the generated documentation book.

[TimUntersberger]

@keepitsane @ramirezmike both fixed.

[keepitsane]

The link to the bar example seems to be broken.
https://github.com/TimUntersberger/nog/blob/master/book/src/configuration/bar.md

The bar example link on that doc page links to the following:
https://camo.githubusercontent.com/30c1dd73e3fa966b419c673d749caf4912afed69b5ee2c8fe3edcdce24899697/68747470733a2f2f74696d756e746572736265726765722e6769746875622e696f2f6e6f672f5f6d656469612f6261722e706e67

I finally realized what my issue was with using the nog.launch binding. In the old rhai configs, I had strings with backward slash escapes

C:\Program Files\vim\gvim.exe

But the new parsing crashes on the . However it works with forward slashes

C:/Program Files/vim/gvim.exe

I don't know if it's something worth fixing but maybe we should add a note in the launch documentation instead?

In previous versions it used to be double back slashes, now it is double forward slashes. Maybe a note should be included of this change in a migration guide for those using the old .nog configs?

[frek818]

There is a large gap in getting from 0 to 1. I think I'm reasonable technical but I'm having a touch time getting started. I'm coming 'yabai' + 'skhd' on MacOS and 'i3' on Linux so perhaps it clouds my understanding. I expect a fairly straight forward process to standing up a minimal nog. Ideally nog would explicitly configure the config.ns with at least:

• A basic bar
• A couple workspaces
• hotkeys for:
  • moving between workspaces
  • opening new windows
  • resizing windows
• Other basic things

It would be a good baseline to get someone acquainted with how nog works. From there, they can get more information from the existing docs.

The blank config.ns presented a bar but beyond that I had no clue how to operate nog. Next I copied the example config but I still find that I'll getting something basic to happen is not completely apparent.

[ramirezmike]

Perhaps we should have nog copy a baseline config on startup if none exists. There are some defaults it loads but I think without a config.ns you may not get many keybindings

A couple workspaces

The way nog works it won't show a workspace if it's empty, so.. I don't think we can just configure workspaces that appear. Is that what you mean?

opening new windows

This is really dependent on what programs are installed on the user's machine. Do you mean a keybinding for making nog manage an existing window or do you mean a keybinding for launching something like chrome?

It would be a good baseline to get someone acquainted with how nog works. From there, they can get more information from the existing docs.

Are you suggesting something like an in-app tutorial or just better defaults in the config?

Next I copied the example config but I still find that I'll getting something basic to happen is not completely apparent.

Feel free to post more questions and I can walk you through it or maybe open a topic in discussions. I'd like to get the documentation to a state where it's much more user friendly and knowing where the pain points are helps.

[TimUntersberger]

#259 will contain a rewrite of the documentation so if anyone has any feedback regarding the documentation please tell me now so I can consider it when rewriting the docs.

[frek818]

It turns out that the example configurations worked just fine. It was just a bit intimidating to start nog and then not know what to do next. So here are a couple of things that I think could improve the on-boarding experience.

1. The example configs should be installed by default rather than an empty config.ns. They are a good starting point.
2. The quick start guide should walk new users through operating nog based on the example configs. For example:

• Start nog by running nog.exe at a command prompt. When nog starts the regular task bar is hidden and the nog bar is added to the top of the screen.
• To quit nog press 'Alt+X'. The nog bar is closed and the windows taskbar is replaced. In the keybindings.ns file there is a keybinding for 'Alt+X' that triggers a call to the nog.quit api.

Currently the docs are decent at providing reference information but the Quick Start guide doesn't live up to it's purpose. Quick Start guides should be based on concrete example of how to basically operate the software. The current Quick Start guide only explains how to install nog.