top | item 46394440

(no title)

beasthacker | 2 months ago

I wanted to share a quick piece of feedback from a potential reader's perspective: There are several small inconsistencies in the intro text (e.g., inconsistent capitalization of 'Rust' vs 'rust', grammar typos).

In a domain like OS development where extreme precision is required, these small errors can subconsciously signal to readers that the technical details might also be imprecise. A quick polish of the documentation would go a long way in establishing authority and trust for the rest of the book.

discuss

order

Sagi21805|2 months ago

Hi! I am the developer of this, and I really appreciate the feedback!!

The book is still on development and this is why I didn't even publish it here, I just recently finished the highlighter which was a lot of work, and I probably will require more.

Currently I am trying to make book and OS unique by developing and creating an explanation on AHCI, which I didn't see much on the internet. And then I try to handle all of the grammar, and typos

threethirtytwo|2 months ago

I couldn’t care less. It always pisses me off when a reviewer of my PR just flags the entire thing because of inconsistent capitalization. It’s the right correction and I always follow through but it’s also pedantic.

It’s technically more correct. But it’s also not a very big deal. Actually it matters more in code for search-ability but for documentation and comments? Give me a fucking break.

madeofpalk|2 months ago

Isn’t being technically correct an important thing for technical documentation that aims to be technically correct?

clutter55561|2 months ago

I see nothing pedantic in flagging capitalisation errors, but I see loads wrong with imposing one’s sloppiness on others.

windexh8er|2 months ago

Attention to detail is important for many and is often a first touch with an end user. I agree with OP, if documentation is sloppy or inconsistent (I'm not saying the doc in question is because I haven't read it) it definitely reduces the impression that it's correct or reliable.

I've skipped even trying software because of poor documentation and so the response of:

> Give me a fucking break.

...seems shallow / callous.