Updates to Basics / Values and Types, up through the text section #11
Conversation
Some of these changes are debatable, so I'd love to get your feedback.
✅ Deploy Preview for haskell-docs ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
|
Thanks for doing this! Partway through reviewing (but will finish later today). Generally, my comments are aimed at the style, in particular trying to avoid explanatory prose where possible in favour of clear examples followed by commentary (not always possible) |
There was a problem hiding this comment.
OK, review complete. Sorry for the number and detail of the comments! (I figured that being picky was the best way to align on style). Feel free to disagree, of course.
General feedback: I'm putting a very high cost on prose in the main narrative of the docs, so most of the comments are of the form: is there a way that this information can be communicated implicitly or references against a different section. The reasons are:
- Avoid overwhelming reader with too many concepts
- Give the reader a choice of how deeply to read (i.e. ignoring comments, boxes).
| @@ -2,89 +2,224 @@ | |||
| comments: true | |||
| --- | |||
|
|
|||
| ## The type of Booleans | |||
| Haskell's type system is such an important feature, and so useful for understanding the language, that it is a good place to begin. This section will explore different Haskell values and their types. | |||
There was a problem hiding this comment.
"This section will explore different Haskell values and their types." - on reflection, I could probably leave out this sentence, since it's evidence from the table of contents.
|
|
||
| * An *expression* is a piece of Haskell source code that describes a value. | ||
| * A *value* is the meaning of an expression. | ||
| * A *type* is a category of values or expressions that can be used in the same ways. |
There was a problem hiding this comment.
Newcomers may be primed to misinterpret the word "category" here if they've heard of the Haskell link to category theory.
| * A *value* is the meaning of an expression. | ||
| * A *type* is a category of values or expressions that can be used in the same ways. | ||
|
|
||
| For example, `True` is a Haskell *value*. Its *type* is `Bool`. There are several other Haskell *expressions* (like `True && True` or `False || True`) that have the same value. In Haskell, we can state this as: |
There was a problem hiding this comment.
My suggestion would be:
"For example, True is a Haskell value. Its type is Bool. Other Haskell expressions may have the same value:"
Then in code comments, we could state, in case still unclear, that (True && True) is an expression with the same value as True.
| `True` is a value in Haskell. Its *type* is `Bool`. In Haskell, we can state this as: | ||
| ## The type of Boolean values | ||
|
|
||
| Here are three words that are central to understanding Haskell. |
There was a problem hiding this comment.
I sympathise with the intent here, and now realize I was using "value" not very carefully - thanks for addressing that! My only objection is that I want to avoid didactic prose as much as possible. My suggestion would be to put lines 11-13 in a "!!! Note" box after the repl example.
That fits the intended style better, which is: example + comments + parenthetic commentary
| ``` | ||
|
|
||
| Similarly, | ||
| 1. A source file contains *declarations* instead expressions, so we define new variables. It's also possible write `example1 = True :: Bool`, but it's unusual. More commonly, Haskell source files contain the type of a definition on a separate line from the value as shown here. |
There was a problem hiding this comment.
Maybe just:
"A source file contains declarations, like example1 = True. It's also possible write example1 = True :: Bool, but more commonly, Haskell source files contain the type of a definition on a separate line from the value as shown here."
|
|
||
| `Int` is a type for integers, as in: | ||
| `Int` is one type for integers. An `Int` is a signed integer with a fixed number of bits, but the exact number of bits depends on the Haskell implementation and architecture. |
There was a problem hiding this comment.
Can this additional info be in a footnote?
| x = 5 | ||
| ``` | ||
|
|
||
| Sometimes you might want to work with integers whose values can be arbitrarily large. For this, there's another type: `Integer`. The same expression, `5`, can be used to describe an `Integer`, as well! |
There was a problem hiding this comment.
Might be nice in an optional "??? Tip" section.
| y2 = 5 * 1000000000000000000 | ||
| ``` | ||
|
|
||
| An expression like `5` that can more than one type is said to be *overloaded*. It can describe different values depending on the type it's used as. |
There was a problem hiding this comment.
Given the subsequent Gotcha section, and the part you added, I think this is redundant.
| ```haskell | ||
| {-# LANGUAGE OverloadedStrings #-} --(1)! | ||
| import Data.Text (Text) | ||
| Floating point numbers are fixed precision, so doing computations with them can result in rounding error. An exact option for numbers with a fractional part is `Rational`, which can represent any rational number (that is, any fraction) exactly. |
There was a problem hiding this comment.
Footnote or optional text box.
| c2 = 'b' | ||
| ``` | ||
|
|
||
| `Text` is the best type for most sequences of characters. However, there's a bit of boilerplate needed to use it. |
There was a problem hiding this comment.
I have a slight preference for not saying there's boilerplate, but just having code comments for the import line and the extension line, in the service of a "show, don't tell" style. But I won't die on this hill.
|
I'm going to close this while I decide what I think about contributing to documentation with copyleft licenses... |
@cdsmith Some context: I don't know anything about licenses, and added this on the suggestion of someone on discourse: https://discourse.haskell.org/t/haskell-guide-cross-posted-on-reddit/5605/8 . The last thing I want is to have a license which discourages anyone from contributing, so I'm more than happy to change/remove this. What would you recommend as a non-controversial choice? |
I replaced the copyleft license with the permissive Creative commons one for now. |
|
Hi, I just wanted to check in on this PR, in the spirit of moving towards a "version 1" of this guide. I'm happy to attempt the suggested changes myself if you'd prefer. |
Some of these changes are debatable, so I'd love to get your feedback.