briandominick
Adds "Coding in Regex" chapter for re-review
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!
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
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!
Thanks for those great reviews @evbacher and @timothymcmackin! Much appreciated feedback. The next commit will reflect most if not all of these suggestions.