Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update about-this-handbook.md #804

Closed
wants to merge 1 commit into from
Closed

Conversation

msiyer
Copy link

@msiyer msiyer commented Jul 14, 2024

  1. Starting positively is important: describing the purpose of the handbook is more important.
  2. Sentence describing what not to expect from the handbook has been moved to a better place. This can even be turned into a callout.
  3. Consistency: replaced the word document with handbook.
  4. Grammar edits: a) a comma must precede "and" that joins two independent clauses; b) article usage.

1. Starting positively is important: describing the purpose of the handbook is more important. 
2. Sentence describing what not to expect from the handbook has been moved to a better place. This can even be turned into a callout.
3. Consistency: replaced the word document with handbook.
4. Grammar edits: a) a comma must precede "and" that joins two independent clauses; b) article usage.
@Vaelatern
Copy link
Member

Counter argument: Describing the negative purpose of the handbook, "This is NOT," is also important. If it goes anywhere later than the first sentence, fewer people will read it.

@msiyer
Copy link
Author

msiyer commented Jul 14, 2024

Counter argument: Describing the negative purpose of the handbook, "This is NOT," is also important. If it goes anywhere later than the first sentence, fewer people will read it.

It is definitely important. This is the reason I proposed turning "This is NOT" into a "warning" callout.
However, "This is NOT" should not be the first sentence. The purpose must be the first sentence.

@msiyer msiyer marked this pull request as draft July 15, 2024 03:51
@msiyer
Copy link
Author

msiyer commented Jul 15, 2024

@Vaelatern do you think the changes add value? should i add the callout for "This is NOT", make all checks successful, and commit again?

@tranzystorekk
Copy link
Contributor

These changes feel mostly stylistic, without any substantial addition or correction. Unless there's some additional value I'm missing, it doesn't seem worth to include them.

@ahesford
Copy link
Member

Adding "an" in the "Example Commands" section changes the meaning of the sentence and is not correct.

Given the number of people who approach the documentation (and the IRC channel) expecting remedial Linux tutorials, emphasis that this guide is not intended to provide such content deserves top billing.

@ahesford ahesford closed this Jul 15, 2024
@msiyer
Copy link
Author

msiyer commented Jul 15, 2024

sure guys. whatever floats your boat.

@msiyer msiyer deleted the patch-1 branch July 15, 2024 15:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants