Adds "Coding in Regex" chapter for re-review

[briandominick]

This whole chapter is fleshed out and re-opened to review.

TL;DR: If you know what you're doing on GitHub, here's a rendered PDF of the chapter. Thanks for checking it out!

I know several people who volunteered to review this chapter expressed an interest in learning Git/GitHub at the same time, which is awesome. All we're going to learn at this point is GitHub, so we can review the contents of this chapter inline. There are enough people participating that hopefully we'll get some good chaos going and folks can see how a lively PR review goes.

What is a PR (review)?

A PR is a pull request, which is a very cool, poorly named concept. Really this is a merge request -- I am submitting a Git branch for consideration, hoping it will get merged into the master branch (or in some cases into a trunk other than master). So a PR or MR review is the stage in the Git workflow at which somebody responsible for reviewing code -- or docs-as-code ;-) -- will approve and/or carry out that final merge.

Which is the long way of saying, this is the step/feature of GitHub that lets us analyze our code diffs before we commit it to master.

So what are we looking at?

This is a chapter of my book Codewriting, which am I writing in this very open-source repo. The book is and always will be free, and you're actually welcome to contribute to it. You are doing that already by giving this chapter a review, for which I thank you.

The book is written in AsciiDoc markup, which is what you'll be looking at if you choose to insert any inline comments. I recommend you first read the rendered chapter (PDF).

So what do we do?

If you have any feedback, you can start a review or pile on to others' comments. Go to the Files changed tab and insert comments inline. Since I write in ventilated prose (one-sentence-per-line), you can comment on any sentence individually.

I'm open to everything from correcting typos to open-ended critiques of my instruction/explanation style to recommending a better chapter title ("Coding Regular Expressions"?). Bonus points for anyone who finds inaccurate regex patterns in my examples!

Finally, if Write the Docs folks want to do more of these, or set up any kind of group learning around Git/AsciiDoc/docs-as-code, I'm very interested in learning how better to convey these concepts, so let me know. You can also comment on the whole PR below without submitting a full review. Thanks for checking out my work!

[mjang]

You've done some great work here!

I think your work assumes some level of knowledge of wildcards and variables that your audience may not have. If your intention is to turn this into a longer book, I might start with a chapter on wildcards, with examples that you could use at the command line.

Your intro is a little discouraging, with words like "notorious" and "difficult". If I were afraid of regex, I might run away after seeing that intro.

If I were new to regex, I'd want some examples that I could practice with, starting at a "Hello world" level (e.g., how to find all instances of "Docs" in a file). Then you could congratulate the reader, and tell them that they've started their journey

[briandominick]

Thanks for the review, @mjang! I think you're probably right all around. This is Chapter 8, and variables are definitely addressed earlier. I think the book might be for slightly advanced audience. I think I assume if you're not already a technical writer, you're a developer looking to do more tech writing. But that doesn't mean all of the chapters have to assume that. Certainly not this one.

As for the part about calling it "notorious" up front, I did that intentionally so readers know I'm not just another person trying to instruct it without realizing people find it really hard. I'm curious what others think about that part. I may ask in WtD Slack #general, since I think that's a general enough issue. Thanks again!

[timothymcmackin]

This is a good start! I've made some suggestions that I think will ease beginners into the topic more smoothly.

[timothymcmackin]

How about a more task-based title here, like "Using regular expressions to automate your work"?

[briandominick]

My chapter titles are 2-3-word format. I wonder if I should reconsider that.

[timothymcmackin]

Before you tell me that regex is difficult, tell me what it's useful for, to get me psyched up to deal with cryptic syntax because it's worth it.

[evbacher]

Yes, I'd start off with a simple but realistic example of a regex and what it can do. Maybe something like

newText = text.replace(/word/g, 'new word');

to replace instances of 'word' everywhere with 'new word'.

Then point out that regex is more than just substring matching, it also knows about things like word boundaries. So you could make that last expression a bit more robust (so you don't end up with things like "sword" transforming to "snew word").

newText = text.replace(/\bword\b/g, 'new word');

You don't want to go too far down this road in the beginning, of course, but at least it gives a hint of the power without just saying it has a notoriously steep learning curve.

[timothymcmackin]

Recommend that you move the "Why" of regex up higher, or else the first section is mostly "regex is hard." You might also separate the "Why regex is useful" info from the cost-benefit analysis of automation, because they seem like different topics to me.

[timothymcmackin]

"Not only can regular expressions search for patterns in text, but they can extract data from the matched patterns and pass that data to an application for further manipulation and storage."

[timothymcmackin]

Recommend that you either summarize these three regexes or say that you'll explain them later, otherwise beginners aren't going to see why that gibberish of symbols is useful here. Regexes are really hard to read and parse if you didn't write them, and in this case you're writing for complete beginners. I'd run away screaming from that first one as a beginner.

[timothymcmackin]

You're undermining your point by saying that you don't get to use regex often. Maybe say instead that while search fields in some applications can accept regexes, regex is even more useful in programs and scripts.

[timothymcmackin]

Maybe add "... but not the following strings:" and some examples?

[timothymcmackin]

Need a better summary of the regex code here. Explain more clearly what's within the parens.

[evbacher]

This is a really good point. You might want to point to your favorite regex resources here. No need to reproduce.

Also, some regex testers, like regexr.com and regex101.com can be really helpful.

[briandominick]

Thanks for those great reviews @evbacher and @timothymcmackin! Much appreciated feedback. The next commit will reflect most if not all of these suggestions.