Write a user guide for new users

[mwoffenden]

I don't understand how many of the layouts work. Can you provide a cheat sheet explaining each one in detail?

BSP is especially mysterious.

Also, is it better to add all layouts to the list? And, is the order of the layouts at all significant?

And what is "enable HUD about?"

Trello Card

[floodedcodeboy]

Okay so I can help with the HUD explanation: HUD stands for "Heads Up Display" When you enable it and you swap between layouts - the HUD will appear and display the current layout.

[ianyh]

The order of the layouts is not particularly significant other than it determining the order they cycle through. As for how the layouts themselves work there isn't a good central explanation for them other than the code itself.

[devvyn]

Indeed, I'm struggling to understand how BSP is, well, a layout at all. It seems to be fullscreen/floating without window cycling, leading me to believe there's a special interface I haven't been introduced to as a user, or a bug preventing the BSP layout from functioning as expected. I'm leaning toward my own ignorance as the best explanation, so a little help with the expected behaviour of the layouts would be appreciated.

(I've used xmonad, awesome, dwm and i3 before Amethyst, so if there's an equivalent that can be pointed to, perhaps that would suffice for illuminating the matter of expected tiling behaviour.)

[alexkrolick]

BSP (Binary Space Partitioning) divides the remaining space in exactly half for each window, alternating vertical and horizontal splits.

---------------------------------------
|                   |         2       |
|        1          |_________________|       
|                   |   3    |____4___|
|                   |        | 5  | 6 |
---------------------------------------

I think a little ASCII diagram in the comment header for each layout file would go a long way, btw.

[ianyh]

ASCII diagrams are an interesting idea, actually.

[ianyh]

@devvyn you may have been running into a bug fixed by #610.

[devvyn]

@alexkrolick Thanks for the diagram. That nicely confirmed that I was experiencing a bug.

@ianyh Ah, yes, after update I see BSP at work, as described. JetBrains IDE windows in particular were a problem, but seem to be cooperating.

[mwoffenden]

After some trial and error, I have decided to try using Amethyst with a single preference: "tall-right". This layout seems to be the most well-behaved for my needs.

However, I think we all still need a help page (ideally within the app itself) explaining all of the following:

• What is each layout and an example picture/drawing of each.
• How exactly does the app work with multiple layouts selected in preferences?
• What is the significance, if any, of changing the order of the layouts as selected in preferences?

The explanation of BSP above is a good starting point.

[alexkrolick]

What is each layout and an example picture/drawing of each.

Ideally this could be generated from the source into a doc page for each layout. A block comment header would be a good start, though.

How exactly does the app work with multiple layouts selected in preferences?

Only one can be active at a time (per workspace). You can switch the active layout using the keyboard shortcut (Alt-Shift-Space). Layouts that are not enabled are not able to be activated using the switcher.

What is the significance, if any, of changing the order of the layouts as selected in preferences?

The order is the order through which the layouts are cycled using the shortcut.

If you enable more than one layout you will be able to observe this behaviour.

[ianyh]

One possibility for the short term is to direct to the xmonad docs, which are actually pretty good. They obviously miss some macOS specifics, but the broad strokes are there.

[MarioRicalde]

@ianyh I've been consistently using Amethyst for the last week or so. And I must admit that I enjoy using it quite a bit. Having 6 displays surrounding me makes window management a nightmare sometimes. And Amethyst has solved this for me... for the most part.

Now, let's talk about what frustrates me about Amethyst. The documentation. I read someone in the issues section mentioning this mysterious .amethyst file and it took me going through the README history to discover things about Amethyst.

Currently, the README is not exhaustive because, from my understanding, it was stripped down some years ago to keep it simple. However, there's no wiki or any other source of documentation ( at least not that I can find easily ) where the information was moved into. Or not one that I can easily find as a new user.

I personally prefer having a huge exhaustive README over a small README without any documentation at all complimenting said file.

For what is worth I found the default .amethyst file! 🎆 🎉

[mwoffenden]

Agree with @MarioRicalde that we need some documentation. Prefereably built in via the right-click menu. Personally I do not want to see a huge document -- but just one that covers all the main features.