Hacker News Reader

Comment by lexicality | Hacker News Reader

Immediately put off by an egregious error in the Aggregate Types section in the very first chapter:

> Unlike the bool version, if a library user were to accidentally flip the order of the arguments, the compiler would immediately complain:

  error[E0423]: expected function, found macro `print`
    --> use-types/src/main.rs:89:9
     |
  89 |         print(Output::BlackAndWhite, Sides::Single);
     |         ^^^^^ not a function
     |
  help: use `!` to invoke the macro
     |
  89 |         print!(Output::BlackAndWhite, Sides::Single);
     |              +

which is a compiler error for calling the wrong function, not swapping the arguments.

Was this book not proof read at all? Is it AI generated? I'm not sure I can trust anything in it any more if something this basic was allowed through.

View on HN

As a heuristic, you should treat obvious errors in the body of a technical text as a red flag, but don't be so harsh on mismatched examples or diagrams. That stuff is notoriously easy to mess up and doesn't tell you anything useful about the amount of thought or revision that went into the writing of the piece.

A more constructive thing to do than blaring the "FAIL" klaxon at the first such mistake is to just let the author know.

Writing is hard but a cursory proof reading would immediately spot that the first line of the error is completely unrelated to the description.

What other more subtle errors are also there?

Speaking as someone who writes and puts stuff online, there are probably approximately 1.2 zillion subtle errors.

The best thing you can do is point them out so the author can fix it for posterity.

In a classic publishing environment, sure, edit the shit out of it before launch. But this isn't that environment. The fastest way to get quality, free content out there is to publish something and then have everyone tell you what's wrong, fix it, and move on.

Working together this way, we produce libraries of material for anyone to use.

This is really weird code because `print!` in Rust always takes a format string (similar to C's printf but as a macro), but I don't see one here. So it's not just a single-character typo.

If you read the text, which has since been fixed, it appears that the example output was incorrect and a print_page function was intended.

It does indeed need to be proofread and that is annoying. It seems to me like the author just copy-pasted the completely wrong compiler output. Because in that section, he's trying to show how by having two distinct types for the arguments, the incorrect order would lead to a compiler error, as opposed to the case where both args were of type `bool` (and that this helps you avoid hard-to-spot mistakes at the point of invocation)

If they'd used a sane document language like LaTeX instead of markdown, it would have been trivial to actually run the examples on build.

Markdown has it's place... books is not it.

I agree LaTeX has it's uses, but... markdown can also do this trivially. See for example the Rust Book [1], and `cargo test` automatically runs example code in markdown doccomments.

[1] https://doc.rust-lang.org/stable/book/ch01-02-hello-world.ht...

The book is written in mdbook which has built-in support for testing Rust examples [0], as well as running examples on the playground [1].

[0]: https://rust-lang.github.io/mdBook/cli/test.html

[1]: https://rust-lang.github.io/mdBook/format/mdbook.html#rust-p...

Reply on news.ycombinator.com