At The Command Line

So I worked on this initially as something for my technical presentation/communications class, one of three I did last semester.
The primary focus in those classes is building up a rough sense of how to do what gets called “business writing,” such as proposals, business blogs, letters, presentations, formal emails, and other similar work. I’ve been teaching this forever, probably in some variation since I started teaching, so I can generally run through a semester in my sleep (not literally, but in a “I’ve taught this regularly for a while now” sort of way). I’m a big fan of teaching basic mechanics in understanding literature and in understanding writing, because it’s something that I was sort of naturally inclined towards but I know that others aren’t, and reading and writing are skills that actually come up a lot in most “adult” fields. Communication at a semi-professional level is something we really should be focusing some time on teaching, at least at the college level (and the high school level but that’s another story).
That being said, I tried to be a little different with it this last time, using better real-life examples and incorporating them into my lectures as hands-on examples in addition to the templates we’d normally use. Overall my last semester was hectic, probably because I tried a bunch of different and new things, but anyway…
Towards the end of the semester, I had a little chat with Chris Williams about his book and how any sort of technical writing similar to what we had to do in class played into the process of the creation of his book. I don’t know how I know Chris online, probably through other people I follow and who follow me mutually through social media. I can’t remember. Anyway, I reached out to him to talk to him about his book and the process for it, precisely because the behind-the-scenes and in-front aspects of book work and nonfiction overlaps so much with our material through the semester.
I initially just showed/read this short interview in class for my students, but I’ve decided to share it here.
~
41fl5bpubdl-_sx331_bo1204203200_
So your project is a new book. What’s it called and what’s it about?
My book is titled The Command Line for Web Developers. Creating websites has shifted from using desktop applications to going into the command terminal and running commands. This book explains not only how to use the command line through simple non-computer science examples and how it applies in real world web development situations.
What inspired the basic idea for the book, first and foremost?
Using the command line is kind of intimidating. I have worked with many colleagues from beginners to experts that aren’t familiar with it. Most keep their terminal application in its default settings. At most they only use it to past in commands they got from the web without understanding what they’re doing. They certainly don’t feel comfortable troubleshooting things when errors come up. So I wanted to give them something that shows just how easy and powerful working from the command line can be.
After that initial idea, how did you proceed with expanding that? Was there an element of “I want this, so it should be available?” in moving forward, or more recognizing both a demand and a need?
Ya, the first thing I did was convince myself what a stupid idea it was. Once I got over that, I talked with a friend who had written a book before and got his advice.  He’d been through the process of working with a publisher, he knew my strengths and could talk to what I should expect.  What really convinced me to write the book was when he told me he wished he had that book to read for himself.
Was there any sort of feasibility research or reading before moving forward?
The publisher I initially worked with did market research both internally and through surveys. I did have a bit of a grilling from the editors in chief over a conference call where we reviewed the survey results. I think the challenge for them was that I wasn’t writing about a specific language or discipline. So they questioned if I was covering enough topics for such a nebulous subject. I maintained that my book wasn’t to be some exhaustive tome that was everything for everyone, but rather it is to be a primer on several subjects to get everyone on the same page.
We also checked out other books that covered similar subjects, what specifics they covered, how that differed from what I was writing, and what would my readers benefit from that they couldn’t get from the other books.
To lay out the whole thing, including visuals and step breakdowns, what did you consider
When I wrote my outline, I planned that each chapter built on knowledge from earlier chapters.  So Chapter 2 covers basic Bash commands, and Chapter 3 gets deeper in extending those commands.  At the same time, the reader wouldn’t have to read from the beginning to the end if they didn’t want to. If they had specific issue with Git for example, they could just to that portion but I needed to make sure they knew they could go back to an earlier chapter if they needed to.
From the outline, I wrote a plan for each chapter.  Why was the chapter important? are there any prerequisites? What are the new concepts? What diagrams and examples will I use.  I write these answers out and keep them as a checklist. It’s not perfect though. Sometimes I went back and revised the plan as I discovered a better way to tackle the chapter.
The diagrams used were mostly annotations for command syntax.  We’re working in the Terminal app, so to show a command, I ended up with a lot of thought bubbles to point out the “new” items we haven’t encountered before.
Inline image 1
I wrote everything in MarkDown. It covered 99.99999% of any formating I needed.  PanDoc is a unix tool that does a great job converting my Markdown to virtually any format, so I could send Word Docs to my editor, and ICML files to InDesign where I ultimately ended up for creating the book file used in printing.  Illustrations were sketched on paper and I just used a pic of it for a placeholder until I could move it to Illustrator.
The overall arc of this class has been to look at different rhetorical models of business/tech communications and how those models work. Throughout this whole project, how important has business communication and having a sense of how to express technical steps and information in written form been?
I needed to demystify an archaic technology with deep institutional knowledge to a group of readers that may have never used it before, which may not have been a part of their education or background. The last thing I wanted was to turn people off by sounding academic or overly technical.  So I tried to keep my tone as conversational as possible even if it sacrifices exact technical precision.
For example, back to Git, someone new to using it would be less concerned about how Git has its own filesystem for capturing snapshots of data than knowing Git tracks changes in code. I’m more concerned in helping the reader get up and running to succeed (although there are footnotes to learn more).
That goes back to answering my chapter plans: why is this important, who care, what  are the new concepts, etc.
Thanks!
Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s