Fixup and improve book using_modules.md #1608
Conversation
|
Unrelated CI issue has suggested fix in #1606 |
The relative example follows afterwards. This block only contains docs on absolute paths.
`$env.NU_LIB_PATH` does not exist In the block that follows the correct name is being used.
The blocks demonstrate different things, but it's confusing to have different code - mixing both behavior changes through context and unnecessary code changes.
Increases readability and clarity. Using 'simply' can indicate that actions are simple. But adding it without a need for differentiation or qualification, they increase sentence complexity, making it harder to read and parse. The statements remain just as valid without them.
The concern before this one already has split sections. Rather than a block with two mixed concerns, and a need for "or" text in a mixed-concern example attempting to demonstrate two things at once, having two blocks makes it much more obvious, distinct, and reference-able (when the reader is only interested in one aspect). It also simplifies the NU_LIB_DIRS concern a lot. Instead of a long block headline with a lot of mixed information, we do the same as the other concern earlier in the document: note the information in an important note block.
Kissaki
force-pushed
the
fix/usingmodules
branch
from
c769824
to
1abe662
Compare
|
@NotTheDr01ds has been making changes to modules too. I'd like to get his take on this before we land it. |
There was a problem hiding this comment.
Thanks for the updates! I've submitted feedback on most of them. @fdncred - Would appreciate your opinion on my feedback as well if you get a chance. Thanks!
| @@ -25,7 +25,7 @@ The example above uses the [Standard Library](../standard_library.md), a collect | |||
|
|
|||
| ## Installing Modules | |||
|
|
|||
| Installing a module is simply a matter of placing its files in a directory. This might be done via `git clone` (or other version control system), a package manager such as `nupm`, or manually. The module's documentation should provide recommendations. | |||
| Installing a module is a matter of placing its files in a directory. This might be done via `git clone` (or other version control system), a package manager such as `nupm`, or manually. The module's documentation should provide recommendations. | |||
There was a problem hiding this comment.
I think "simply" works better here for the users' of modules. It explains to users why we're not going into a lot of detail in this section.
| When importing a module via a relative path, Nushell first searches from the current directory. If a matching module is not found at that location, Nushell then searches each directory in the `$env.NU_LIB_DIRS` list. | ||
|
|
||
| This allows you to install modules to a location that is easily accessible via a relative path regardless of the current directory. | ||
| ::: | ||
|
|
||
| - An absolute or relative path to a Nushell module file. As above, Nushell will search the `$env.NU_LIB_DIRS` for a matching relative path. | ||
| - An absolute path to a Nushell module file: |
There was a problem hiding this comment.
I did have "absolute" and "relative" split out originally, but I combined them since there is so much duplicated wording in the "split" version. While I think it's better combined, I can certainly see reasons for splitting relative/absolute into separate bullets as well. However, if we split them, then (a) We should move "relative" above "absolute" since it is the most common form. And (b) I would recommend not duplicating the entire "Important" block - Just reference it the second time, rather than repeating it.
There was a problem hiding this comment.
Before the fixup, the first two was split and the second was combined. I think that asymmetry should be solved, one way or another.
I agree with order should be relative before absolute
I prefer self-sufficient explanations, without pointing to earlier sections. I would prefer duplication over pointing elsewhere, especially if it's not a anchor jump link
Given the noteworthy concerns, maybe it makes more sense to combine the two absolute and the two relative blocks? 🤔
There was a problem hiding this comment.
Before the fixup, the first two was split and the second was combined
Given the noteworthy concerns, maybe it makes more sense to combine the two absolute and the two relative blocks?
Ah - I think I had a good reason for it, but I also agree with you on the symmetry. I'll take another look at it, but it might be a few hours.
| @@ -100,7 +114,7 @@ The path to the module can be: | |||
|
|
|||
| ::: | |||
|
|
|||
| - Less commonly, the name of a module already created with the [`module`](/commands/docs/module.md) command. While it is possible to use this command to create a module at the commandline, this isn't common or useful. Instead, this form is primarily used by module authors to define a submodule. See [Creating Modules - Submodules](./creating_modules.md#submodules). | |||
| - Less commonly, the name of a module is created with the [`module`](/commands/docs/module.md) command. While it is possible to use this command to create a module at the commandline, this isn't common or useful. Instead, this form is primarily used by module authors to define a submodule. See [Creating Modules - Submodules](./creating_modules.md#submodules). | |||
There was a problem hiding this comment.
This results in a grammatically incorrect sentence flow. Keep in mind that the sentence leading into this list is "The path to a module can be", so the sentence has now gone from:
The path to a module can be ... Less commonly, the name of a module already created with the
modulecommand.
to:
The path to a module can be ... the name of a module is created with the
modulecommand.
However, I agree the original can be improved a bit. How about:
| - Less commonly, the name of a module is created with the [`module`](/commands/docs/module.md) command. While it is possible to use this command to create a module at the commandline, this isn't common or useful. Instead, this form is primarily used by module authors to define a submodule. See [Creating Modules - Submodules](./creating_modules.md#submodules). | |
| - Less commonly, the name of a module that was previously created with the [`module`](/commands/docs/module.md) command. While it is possible to use this command to create a module at the commandline, this isn't common or useful. Instead, this form is primarily used by module authors to define a submodule. See [Creating Modules - Submodules](./creating_modules.md#submodules). |
There was a problem hiding this comment.
ah, you mean to say the list intro "The path to the module can be:" is continued in this sentence?
That's 74 code lines, or four list items each with code block and two warning notice blocks above here. I don't think that can still be considered "sentence flow". A list that is not a list of one-liners should have self-sufficient bullet points / bullet point sections.
I certainly see why I didn't realize what the sentence was referring to / that there's a pre-text to it.
There was a problem hiding this comment.
I see how the other points use that sentence flow so it wouldn't make sense to do that differently here. But I don't think how it was was clear with how distant the whole thing is.
There was a problem hiding this comment.
I think your suggestion clarifies it quite well. But maybe now I'm just aware of the context. Dunno. It seems like it should have the same issue for me, but it doesn't when I read it now.
There was a problem hiding this comment.
Lol - I get it. Yes, "sentence flow" may not be as accurate a description as "consistent bullet styles" (which I'm also okay sometimes deviating from when necessary). Feel free to commit the suggestion if you'd like. Or spend the night on it and see how it looks in the morning ;-).
| @@ -193,7 +207,7 @@ assert true | |||
| # => Assertion passes | |||
|
|
|||
| hide assert | |||
| assert equal 1 1 | |||
| assert equal 1 2 | |||
There was a problem hiding this comment.
These make more sense as assertions that Pass (especially since the following line says that the assertion passes). The point is to show that the error comes because the assert has been hidden, not that an error would have occurred from a failing assertion, so we want all of these to be 1 1 (or another simple assertion that will pass).
If you'd like, you can change them to the 'String1' "String1" example used above? But we shouldn't use a failing assertion like 1 2.
| @@ -208,7 +222,7 @@ Just as you can `use` a subset of the module's definitions, you can also `hide` | |||
| ```nu | |||
| use std/assert | |||
| hide assert main | |||
| assert equal 1 1 | |||
| assert equal 1 2 | |||
| @@ -217,11 +231,11 @@ assert true | |||
| ``` | |||
|
|
|||
| ::: tip | |||
| `main` is covered in more detail in [Creating Modules](./creating_modules.md#main-exports), but for end-users, `main` simply means "the command named the same as the module." In this case the `assert` module exports a `main` command that "masquerades" as the `assert` command. Hiding `main` has the effect of hiding the `assert` command, but not its subcommands. | |||
| `main` is covered in more detail in [Creating Modules](./creating_modules.md#main-exports), but for end-users, `main` means "the command named the same as the module." In this case the `assert` module exports a `main` command that "masquerades" as the `assert` command. Hiding `main` has the effect of hiding the `assert` command, but not its subcommands. | |||
There was a problem hiding this comment.
As above, I think "simply" is useful here. It's used to differentiate definitions:
- Here, we're giving the "simple" definition
- The "Writing" chapter covers the "more detailed" version
There was a problem hiding this comment.
For me the "for end users" and the fact that the sentence is there already implies that this is the ("simple") relevant information - and more details are covered elsewhere as mentioned.
In that reading, the word is redundant to me.
The opposite to simply would be "in a complex way". But the alternative presented here is "more detail" [about the same thing]. Which adds a bit more confusion/irritation for me.
There was a problem hiding this comment.
Does replacing "simply means" with "just means" help at all, or does it have the same issue for you?
NotTheDr01ds
requested review from
NotTheDr01ds
and removed request for
NotTheDr01ds
See individual commits for reasoning.