proofreading and tweaks

Author: starchglazer

src/guide/distribution.mdx

@@ -6,12 +6,15 @@ If you plan to distribute your configuration to a lot of users, you should keep
 a couple things in mind:
 
 ### API Breaks
-Quickshell will have API breaks in future versions.
-You should have a way to track specific revisions with your distribution
-to avoid breakage if a user updates quickshell before you can update your configuration.
+As Quickshell is still in a somewhat early stage of development, Quickshell will
+have API breaks for future versions.
 
-With Nix this should be as simple as tracking a specific revision.
-For Arch, and other distributions without a mechanism to do this, you may
+You should have a way to track specific revisions to avoid breakage if a user
+updates Quickshell before you can update your configuration.
+
+With Nix, this should be as simple as tracking a specific revision.
+
+For Arch, or any other distributions without a mechanism to do this, you may
 want to include a package that builds a specific Quickshell revision with
 your configuration.
 
@@ -20,13 +23,14 @@ Quickshell can load configurations from a number of different paths.
 The ideal path depends on how you distribute your config.
 
 #### As dotfiles
-If you distribute your config as a set of dotfiles, you should place
-the config in `$XDG_CONFIG_HOME/quickshell/<name>` (usually `~/.config/quickshell/<name>`).
-Named configurations can be used in the quickshell command by specifying `--config` or `-c`
-(`qs -c <name>`).
+If you distribute your config as a set of dotfiles, you should place it in
+`$XDG_CONFIG_HOME/quickshell/<name>` (usually `~/.config/quickshell/<name>`).
+
+You should name your config and refrain from using the bare `$XDG_CONFIG_HOME/quickshell`
+directory, as that will make it harder for users to have any other configuration.
 
-You should not use the bare `$XDG_CONFIG_HOME/quickshell` directory as that will
-make it harder for users to have any other configuration.
+Any directory in the `$XDG_CONFIG_HOME/quickshell` can be used using the Quickshell command
+by specifying `--config` or `-c`, like so: `qs -c <name>`.
 
 #### As a package
 Some configurations are distributed as distro packages. These packages should use a

src/guide/faq.mdx

@@ -3,10 +3,13 @@ title: "FAQ"
 description: "Frequently Asked Questions"
 index: 1000
 ---
-This page is being actively expanded as common questions come up again.
 
-Make sure to also read the [Item Size and Position](/docs/guide/size-position) and
-[QML Language](/docs/guide/qml-language) pages for questions related to
+> [!NOTE]
+> This page is being actively expanded upon as more common questions come up.
+>
+> Make sure to also read the [Item Size and Position](/docs/guide/size-position) and
+> [QML Language](/docs/guide/qml-language) pages for questions related to
+> item sizing/positioning and QML in general.
 
 ## Misc
 
@@ -16,7 +19,7 @@ span the APIs exposed by Quickshell, as well as best practice across all
 APIs, but will not change the language syntax or anything exposed by Qt.
 
 Most changes will be relatively trivial, though you may have to make the same
-trivial change a great number of times if you have a large configuration.
+trivial change a considerable amount of times if you have a large configuration.
 
 Migration guides will be provided between each release version.
 
@@ -27,7 +30,7 @@ single process.
 ## How do I
 
 ### Make a rounded window
-Rounded windows are simply transparent square ones with a rounded rectangle
+Rounded windows are simply transparent, square windows, with a rounded rectangle
 inside of them.
 
 ```qml
@@ -46,11 +49,11 @@ inside of them.
 
 ### Make a list of widgets
 If you have a short list of items to display, such as a list of active music
-players or system tray items, you want a @@QtQuick.Repeater, usually combined
-with a @@QtQuick.Layouts.RowLayout or @@QtQuick.Layouts.ColumnLayout.
+players or system tray items, you want a @@QtQuick.Repeater, which is
+usually combined with a @@QtQuick.Layouts.RowLayout or @@QtQuick.Layouts.ColumnLayout.
 
-If you have a longer list, such as a list of entries in an application launcher,
-or a list that needs to scroll, you may want a @@QtQuick.ListView instead.
+If you have a longer list, such as a list of entries in an application launcher
+or a list that needs to be scrolled, you want a @@QtQuick.ListView instead.
 
 ### Run a program or script
 Use @@Quickshell.Io.Process.
@@ -63,10 +66,15 @@ e.g. a command that listens to window manager IPC commands, use
 @@Quickshell.Io.SplitParser to return each datum as it arrives.
 
 ### Show widgets conditionally
-The @@QtQuick.Item.visible property can be used to change the visibility of an
-Item conditionally, as well as Loaders.
+Conditionally showing widgets can be done in two ways, simply using the @@QtQuick.Item.visible property,
+or by using a @@QtQuick.Loader.
+
+Depending on your use case, both the @@QtQuick.Loader and the @@QtQuick.Item.visible property
+may make sense at equal complexity. If you want to unload a widget tree to save memory or
+speed up load times, then you should use Loaders.
+
+Note that you can also change out a Loader's component conditionally:
 
-Note that you can change out a loader's component conditionally:
 ```qml
 @@QtQuick.Loader {
   readonly property Component thing1: ...
@@ -77,9 +85,9 @@ Note that you can change out a loader's component conditionally:
 ```
 
 ### Round an image
-The easiest way to round an image is with @@Quickshell.Widgets.ClippingWrapperRectangle.
-ClippingWrapperRectangle is a [MarginWrapper] component, which will attempt to match
-the size of its contained item.
+The easiest way to round an image is with @@Quickshell.Widgets.ClippingWrapperRectangle,
+which is a [MarginWrapper] component. This component will attempt to match the size of
+its contained item.
 
 ```qml
 @@Quickshell.Widgets.ClippingWrapperRectangle {
@@ -97,7 +105,7 @@ the size of its contained item.
 ### Reference images and resources
 By default, paths passed to components such as @@QtQuick.Image or
 @@Quickshell.Io.FileView as strings are relative to Quickshell's working
-directory. Usually this is not the desired behavior.
+directory. Usually, this is not the desired behavior.
 
 To get a file path relative to the current QML file, you can use @@QtQml.Qt.resolvedUrl().
 
@@ -106,12 +114,12 @@ you can use @@Quickshell.Quickshell.cachePath(), @@Quickshell.Quickshell.dataPat
 @@Quickshell.Quickshell.statePath(),
 
 ### Add a drop-shadow
-If you want a *rectangular*, *round rectangular*, or *circular* drop shadow,
-use @@QtQuick.Effects.RectangularShadow.
-For any other shape, you will have to use a @@QtQuick.Effects.MultiEffect.
+Use @@QtQuick.Effects.RectangularShadow if you want a *rectangular*, *round rectangular*,
+or *circular* drop shadow.
 
-When using a MultiEffect, set @@QtQuick.Effects.MultiEffect.shadowEnabled,
-as well as its other shadow and blur related properties.
+For any other shape, you will have to use a @@QtQuick.Effects.MultiEffect and set
+@@QtQuick.Effects.MultiEffect.shadowEnabled, as well as its other shadow and blur
+related properties.
 
 ### Get rid of the purple/black icons
 The @@Quickshell.Quickshell.iconPath() function has three variants:
@@ -127,19 +135,20 @@ however you can implement your own using @@Quickshell.Io.Socket or @@Quickshell.
 which can be used to parse and send IPC messages.
 
 ### Open/close windows with commands
-Quickshell doesn't come with a command to open or close a window, however you can
-make your own using @@Quickshell.Io.IpcHandler, which allows you to call functions
+Quickshell doesn't come with a command to open or close a window; however, you can
+make your own using @@Quickshell.Io.IpcHandler, allowing you to call functions
 inside of Quickshell with a command. Said functions can change the
 @@Quickshell.QsWindow.visible property of a window, or load/unload it using a
 @@Quickshell.LazyLoader.
 
 ### Reduce memory usage
 The main thing you can do to reduce the memory usage of a given configuration
-is to use loaders. Loaders can be used to create objects only when needed,
-and destroy them when not needed.
+is to use Loaders.
 
-- Use @@QtQuick.Loader when the component being loaded inherits from @@QtQuick.Item.
-- Use @@Quickshell.LazyLoader in other cases.
+Loaders can be used to create objects only when needed, and destroy them when not needed.
+
+@@QtQuick.Loader should be used if the component being loaded inherits from @@QtQuick.Item,
+otherwise, a @@Quickshell.LazyLoader should be used.
 
 ## Something is broken
 
@@ -153,9 +162,11 @@ if the only border property you wanted to set was radius.
 
 ### My window should not be opaque
 If a window is created with an opaque background color, Quickshell will use
-a window surface format that is opaque, which reduces the amount of processing
-the gpu must do to draw it. If you change the background color of your window
-between opaque and transparent colors, this may affect you.
+a window surface format that is opaque. This is done to reduce the amount of
+processing the gpu must do to draw it.
+
+If you change the background color of your window between opaque and transparent colors,
+then this may affect you.
 
-To tell Quickshell to always create a window capable of showing transparency,
+To tell Quickshell that you want to create a window capable of showing transparency,
 use @@Quickshell.QsWindow.surfaceFormat to set `opaque` to false.

src/guide/index.mdx

@@ -6,12 +6,12 @@ index: -1
 See the [Installation and Setup](/docs/guide/install-setup) page to get started.
 
 To write a Quickshell config, start by following the
-[Guided Introduction](/docs/guide/introduction) and skimming the
+[Guided Introduction](/docs/guide/introduction), and skimming the
 [QML Language Overview](/docs/guide/qml-language).
 
-Before continuing on your own, read the [Item Size and Position](/docs/guide/size-position)
-page to learn how to lay out elements in QML. This is significantly different
-from many other layout systems such as CSS.
+After that, read the [Item Size and Position](/docs/guide/size-position) page before
+continuing on your own to learn how to lay out elements in QML. Laying out elements
+in QML is significantly different from many other layout systems such as CSS.
 
 To learn what features Quickshell offers and how to use them, use the
 left sidebar and click through the `Quickshell Types` pages. The sidebar

src/guide/install-setup.mdx

@@ -8,7 +8,8 @@ index: 0
 
 ## Installation
 
-All packages currently track quickshell's master branch. This may change in the future.
+Since Quickshell 0.1, you can now choose whether to install by tracking the master branch,
+or install by latest release.
 
 Note that you may want to install some additional packages (names vary by distro):
 - `qtsvg`: support for SVG image loading (bundled with most packages)
@@ -17,12 +18,13 @@ Note that you may want to install some additional packages (names vary by distro
 - `qt5compat`: extra visual effects, notably gaussian blur. @@QtQuick.Effects.MultiEffect is usually preferable
 
 ### Nix
-Quickshell releases are packaged in nixpkgs as `quickshell`.
+The Quickshell repo has an embedded flake. You can use either of the two:
 
-The Quickshell repo also has an embedded flake.
-You can use either `git+https://git.outfoxxed.me/outfoxxed/quickshell`
-or `github:quickshell-mirror/quickshell`. Use `?ref=` to specify a tag
-if you want a tagged release.
+- `git+https://git.outfoxxed.me/outfoxxed/quickshell`
+- `github:quickshell-mirror/quickshell`
+
+> [!NOTE]
+> You can use `?ref=` to specify a tag if you want a tagged release.
 
 ```nix
 {
@@ -41,20 +43,19 @@ if you want a tagged release.
 }
 ```
 
-The package is available as `quickshell.packages.<system>.default`, which you can add to
-`environment.systemPackages` or `home.packages` if you use home-manager.
+The package is available as `quickshell.packages.<system>.default`, which can be added to
+your `environment.systemPackages` or `home.packages` if you use home-manager.
 
 ### Arch
-Quickshell is available from the aur under
-the [quickshell](https://aur.archlinux.org/packages/quickshell) package for the latest release,
-or the [quickshell-git](https://aur.archlinux.org/packages/quickshell-git) package
-which tracks the master branch.
+Quickshell is available from the aur under:
+- the [quickshell](https://aur.archlinux.org/packages/quickshell) package for the latest release
+- the [quickshell-git](https://aur.archlinux.org/packages/quickshell-git) package that tracks the master branch
 
 > [!WARNING]
-> When using an AUR package, quickshell may break any time Qt is updated.
+> When using an AUR package, Quickshell may break whenever Qt is updated.
 > The AUR gives us no way to actually fix this, but Quickshell will attempt to
 > warn you if it detects a breakage when updating. If warned of a breakage,
-> please reinstall the package
+> please reinstall the package.
 
 Install using the command below:
 ```sh
@@ -65,9 +66,9 @@ yay -S quickshell-git
 (or your AUR helper of choice)
 
 ### Fedora
-Quickshell is available from the [errornointernet/quickshell] COPR, as either
-`quickshell` which tracks the latest release or `quickshell-git` which tracks
-the master branch.
+Quickshell is available from the [errornointernet/quickshell] COPR, as either:
+- `quickshell` that tracks the latest release
+- `quickshell-git` that tracks the master branch
 
 [errornointernet/quickshell]: https://copr.fedorainfracloud.org/coprs/errornointernet/quickshell
 
@@ -90,7 +91,8 @@ Quickshell's source repository works as a channel. Add the following to your cha
   (branch "master"))
 ```
 
-Then, you can install the package via `guix install quickshell-git` or by adding `quickshell-git` to your system or home definition.
+Then, you can install the package via `guix install quickshell-git` or by adding `quickshell-git`
+to your system or home definition.
 
 You can also clone the repository and use `guix shell -f quickshell.scm` to try out the package.
 
@@ -172,13 +174,13 @@ We are aware of the following issues:
 - Qmlls does not work well when a file is not correctly structured.
   This means that completions and lints won't work unless braces are closed
   correctly and such.
-- Qmlls cannot handle quickshell's singletons. This means you won't see
-  completions, and usages of singleton members may show a warning.
-  We're still investigating this problem and how to fix it.
+- Qmlls cannot handle Quickshell's Singleton, which means you won't see completions,
+  and usages of Singleton members may show a warning. We're still investigating
+  this problem and how to fix it.
 - The LSP cannot provide any documentation for Quickshell types.
 
-Keeping in mind the above caveats, qmlls should be able to guide you towards
-more correct code should you chose to use it.
+Keeping in mind the above caveats, qmlls should be able to guide you towards a
+more correct code should you choose to use it.
 
 > [!NOTE]
 > Nix users should note that qmlls will not be able to pick up qml modules