Write an introduction to the entire guide

[quaid]

This should set the tone and stage for the whole book.

Start with a visionary introduction to work against.

[quaid]

Request to @shaunix @bproffitt @semioticrobotic for review of this introduction to the entire guide in preparation for the 1.99 release.

It had been hanging for a few weeks with an unfinished section and an unmerged PR. All of that is solved and merged, and I just did a clean read and final organization/typos fix.

I believe this is ready for you to read as if it's really, truly going to be the introduction to this guide.

[semioticrobotic]

Thanks for incorporating my proposed changes! I will try to read again and leave additional feedback if warranted. :smile:

[quaid]

Reminder to @shaunix and @semioticrobotic to provide any comments, responses, reviews, fixes, etc. to this introduction to the guide. You can make a pull request for any changes or inline-comments for presenting_tosw.adoc or respond here narratively in the issue.

[semioticrobotic]

Thanks, @quaid. It appears you've already accepted/merged most of my edits from the first round of review, but today I will re-read and offer another round.

[shaunix]

L5: There's a trailing c, unless that's some strange piece of asciidoc syntax I'm not familiar with.

L22: The italicized bit ends with a question mark, but the word order doesn't strictly phrase it as a question. I'm aware putting a question mark on a statement can be a stylistic choice. Just make sure it's a choice and not a mistake.

L34: I'm weakly of the opinion that the verb form should be "create", not "creates". Or just make the sentence simpler to avoid the issue altogether.

L54: I'm strongly of the opinion that "end user" is two words, no hyphen, when used as a noun.

L58: Consider a comma after the word "open" to avoid a garden path. I started reading this as "open and welcoming" being adjectvies for "the community".

L101: There's a parallel construction problem here. The preceding list items are noun phrases, but this is a complete sentence. The lone parenthetical sublist above it feels weird to me too.

[quaid]

Thanks, @quaid. It appears you've already accepted/merged most of my edits from the first round of review, but today I will re-read and offer another round.

Thanks, I am just confirming that you feel this is a good enough introduction for the guide, from a factual as well as creative POV.

[semioticrobotic]

Ah! Apologies for misunderstanding the nature of the request.

Yes, I like the framing and tone!

[quaid]

@shaunix Thanks for the review.

L5: There's a trailing c, unless that's some strange piece of asciidoc syntax I'm not familiar with.

My Bluetooth keyboard seems to occasionally transmit a touchpad stroke as a 'c'. The location is wherever the cursor is, so it's a hard thing to search for. It's infrequent enough that I haven't sought a new keyboard. And that is the story of my wayward-c.

L22: The italicized bit ends with a question mark, but the word order doesn't strictly phrase it as a question. I'm aware putting a question mark on a statement can be a stylistic choice. Just make sure it's a choice and not a mistake.

I'll go massage it a bit; the mark was added later, it may need a better approach. I think it's really that it's a faux-quote that started as an emphasis.

L34: I'm weakly of the opinion that the verb form should be "create", not "creates". Or just make the sentence simpler to avoid the issue altogether.

Yeah, rework is the fix, thanks. Now it flows better into the rest of list, using 'people' instead of 'person/persons':

. One or more people needing a solution create the first iteration of the software. . Other people with similar needs start using it, forming the core of the userbase.

L54: I'm strongly of the opinion that "end user" is two words, no hyphen, when used as a noun.

+1 fixed

L58: Consider a comma after the word "open" to avoid a garden path. I started reading this as "open and welcoming" being adjectvies for "the community".

+1 fixed AND I've never heard the term garden path (although I surely know one when I see one).

L101: There's a parallel construction problem here. The preceding list items are noun phrases, but this is a complete sentence. The lone parenthetical sublist above it feels weird to me too.

This is a good catch, thanks. I fixed the parallel construction with some rewording, then moved the sub-list item out to the next paragraph. The flow sees better to me this way. Too much was being hung on the bulleted list.