3 ms·
I suggest you go with prose that clearer over prose that is more stylistic. For example: Line six has a closing curly brace, and so main, and thus, our progra
by kbenson 12y ago
I suggest you go with prose that clearer over prose that is more stylistic. For example:
Line six has a closing curly brace, and so main, and thus, our program, is over.
Could be rewritten as:
Line six has a closing curly brace, and so main is over. By extension, our program is over as well.
Maybe even with a quick reinforcing of the (hopefully earlier explained) concept that main is the main program block.
It's a fine line to walk, making the text interesting while also making it very clear, but I think there's something to be said for making the English easy to parse, since the people going through the tutorial will have enough on their hands dealing with the code examples.
- jonnybgood 12y agoI agree. Dedicated tutorial authors of languages with advanced concepts such as Rust, Haskell, etc. really need to take a course or have a quick overview of technical writing. Steve does a pretty good job with Rust, I think. I wish Haskell had good tutorial authors like Steve. Haskell really needs better tutorial authors. Are CS majors typically required to take a technical writing class like other engineering disciplines?
- maxerickson 12y agoI would move that part up by the first time the code is shown, replacing "This small snippit is enough to start with." with some more concrete description of the program, like "The smallest rust program that will actually do anything." (I'm not sure that is exactly true, just illustrating my meaning). I would then go further than you suggest, saying something like, "The blank lines, 1,3 and 7, do not have any impact on the program." Then "Line 4 binds the value 5 to the variable x.", followed by the explanation of what that is called in rust. After that, "Lines 2 and 6 are the beginning and end of the program. For this program, they also define the scope that owns 'x'." Followed by the explanation of ownership. Once 'let' is established, a short explanation of 'mut' can follow.