stolley.dev

With #PragProWriMo off and running this November, I wanted to share some of my thinking about becoming a better writer. Not by looking at the best of how I write, but at the worst. Motivation can only get you so far if you’ve got a hang-up about your writing.

Simple truths: Everyone writes. Some of us enjoy it. Most of us don’t. And consciously or not, almost everyone has some kind of hang-up about writing. It might represent a mild difficulty, or be something as serious as a root cause of writer’s block. At its worst, it might even be a nagging voice that tells you Sorry, you’re not a writer.

Let me tell you about my writing hang-up. I’ll even demonstrate it for you:

I’m a writer who’s still recovering from graduate school, where you’re positively reinforced—and often richly rewarded with praise and publications—to write extraordinarily complex sentences (no matter what the topic); the more complex the sentence, the more the need to avoid, as long as possible, any kind of terminal punctuation: a sentence-ending period, for example, completes a thought, and no thought is ever complete—so eventually you end up using every piece of punctuation on your keyboard (parentheses, commas, em-dashes, colons, semicolons), and the sentence you’ve constructed spans several lines, and it ends up in a completely different place from where it started.

That’s my hang-up, on full display in that sentence, right there. If you read that whole thing, I’m so sorry.

Sentences like that are what I’ve been working on hardest to improve about my writing. I’ve been making some progress, I guess, because it was actually kind of painful instead of natural to write that terrible, embarrassing demonstration above.

The worst thing about my hang-up with avoiding terminal punctuation is that I write sentences that are beyond saving. They’ve got so many twists and turns that there’s very little that can be saved or properly edited. Those kinds of sentences take on a life and trajectory all their own. I can’t control them any better when I’m trying to fix them than I could on a first draft.

You’ve probably heard writerly advice like “Just let it out! Draft and just keep going!” I’ve heard that, too, but it has never worked for me. It just produces the kinds of awful sentences like I demonstrated above. “Just keep going” is the worst thing I can let myself do, because my hang-up is that I will just keep going. And going. And going. Real Energizer Bunny stuff.

So I edit myself as I write. (Note that self-editing is no substitute for having someone else, especially a professional, edit your writing.) And by constantly working on my writing, I have become very familiar with the many kinds of bad habits I have. After I’ve fixed the worst ones, I can see others: I make myself keep my subjects near my verbs. I try to be sparing about dropping fancy inductive sentences, and instead go with a straight-up subject-verb-object pattern. Usually.

At best, the end result is improved clarity. Or at least writing that isn’t getting in the way of the material I’m trying to convey. There’s plenty of confusion in the mix with technical subject matter already—no matter how skilled a writer you are.

Maybe you’ve got anxiety about your command of grammar (everyone does). Maybe you’re laboring under a bunch of silly myths and lies about writing that you were taught in school: “Never use I,” “Never start a sentence with a conjunction,” or “Never end a sentence with a preposition.” Those are all lies. Maybe you think your writing sounds boring, or maybe you think you’ve not got a big enough vocabulary.

But here’s the thing about a writing hang-up: you’ve got to acknowledge it and hit it head on, whatever it is. Don’t let it become the excuse not to write. Let it be the thing you decide to fix—not before you write, but as you write.

Take my hang-up with long and winding sentences. I’ve found a technique for countering it. And that’s to read more writing by authors who do exactly the opposite of whatever I’m trying to fix in my own writing. Less David Foster Wallace, more Virginia Woolf.

But reading isn’t a good excuse not to be writing, either. To get myself primed to write, I often read just a few punchy, staccato sentences by someone like Hunter S. Thompson, something like this short passage from his classic “The Kentucky Derby is Decadent and Depraved”:

Steadman is now worried about fire. Somebody told him about the clubhouse catching on fire two years ago. Could it happen again? Horrible. Trapped in the press box. Holocaust. A hundred thousand people fighting to get out. Drunks screaming in the flames and the mud, crazed horses running wild. Blind in the smoke. Grandstand collapsing into the flames with us on the roof. Poor Ralph is about to crack. Drinking heavily, into the Haig.

That’s a whole paragraph with only two pieces of non-terminal punctuation (a couple of commas). As an added bonus, it’s funny. It’s visual. It creates a scene. And that activates the better, more creative parts of my brain.

Writing to teach others about technical subjects requires stringing together a lot of complex ideas. A short passage like Thompson’s is enough to remind me that I can have a complete thought or idea (like a burning clubhouse at the Kentucky Derby) and that I can convey it in a number of short, punchy sentences. Not everything can be short and punchy, but changing up from the monotony of longer sentences makes a big difference.

I work on my writing hang-up as a pet project of personal and professional improvement. But that’s really secondary to what I’m trying to do for readers. Every period is a place to rest. A short sentence invites a reassuring, I’ve-got-this re-read for uncertain readers. If readers can retread small or at least manageable steps, they’ll be able to follow me wherever I try to take them. There is no need to try to lead someone through the maze of one massive sentence.

Or so I keep having to tell myself.

It’s the end of May, and I’m now about ten weeks into the contracted part of this project for Pragmatic Programmers. And in the last week, the book has grown from its original proposed 6 chapters at 150 pages to 8 chapters that will weigh in at around 250 pages. That gives me a lot more room to work and should prevent anything vital from having to be cut.

As I put the finishing touches this week on the work for my first major milestone—the three-chapter publisher’s review, which I’d originally planned for mid-June—the table of contents its looking like this, minus an introductory setup chapter that’ll be part of the frontmatter and an appendix showing a signaling channel written in pure WebSockets (the book itself uses Socket.IO in its recently released version 4):

1. Working with a Signaling Channel. Readers set up an interface in HTML, CSS, and JavaScript to manage a basic video-chat app and wire up a pre-built signaling channel and its callbacks. A high-level description of WebRTC contextualizes the signaling channel’s purpose and limited features.
2. Establishing a Peer-to-Peer Connection. Picking up right where the last chapter left off, readers learn to request permissions for camera/mic access and display the resulting stream. They then go on to create a peer connection using the “perfect negotiation” pattern described in the WebRTC specification and build out the rest of the basic video-chat app.
3. Handling Data Channels. Media streaming is WebRTC’s most famous feature, but it’s data channels that really open up the possibilities for all kinds of real-time, peer-to-peer apps. Readers add a video-filter function to the app built over the first two chapters and then build a complete text-chat feature.
4. Streaming Complex Data. Data channels can handle more than simple strings. This chapter opens with building fallbacks into the perfect-negotiation code so they can more confidently test their work, including especially with data channels, on browsers that have poorer implementations of WebRTC (ahem, Safari). Readers work with sending and receiving JSON strings to build out the chat feature further, and then turn to streaming binary data—as either Blobs or ArrayBuffers, using some clever feature-detection—to share images in the chat. Readers build a standalone peer-to-peer file-sharing app to close out the chapter.
5. Building Peer-to-Peer Interfaces. The first four chapters cover all the fundamentals of WebRTC. This chapter looks more closely at real-time, peer-to-peer interface design—all framed by accessibility. Readers learn to build interfaces that take advantage of semantic HTML and ARIA attributes, while also giving users greater control over real-time interfaces, such as arranging interface elements in relation to their cameras.
6. Managing Multi-Peer Connections. This chapter moves from one-to-one to many-to-many WebRTC apps. Sticking to the browser-based focus of the book, it introduces a mesh-network architecture for connecting three or more peers in a single call. Readers also learn the practical and theoretical upper limits to the number of simultaneous peer connections, and begin to work with the RTCPeerConnection.getStats() interface.
7. Optimizing Media Streaming. Readers take a deep dive on different media APIs in this chapter, and learn to optimize streaming media based on local and remote statistics and even the simple appearance of media streams in the browser (how big does that video stream need to be? how small can it get?). The chapter also looks at current and forthcoming methods for optimizing images sent over data channels, including the exciting but currently not universally supported self.createImageBitmap() method.
8. Deploying WebRTC Apps to Production. This final chapter of the book looks at what it takes to deploy a WebRTC app into production. Readers learn about using public STUN servers as well as setting up a private STUN/TURN server, with the TURN component as a fallback for when a direct peer-to-peer connection cannot be established.

There are a lot of topics packed into chapters six, seven, and eight especially. So I wouldn’t be surprised to discover a topic that deserves its own chapter—either on my own as I write or from feedback that’ll come in from the technical and beta reviews later in the summer.

The first three chapters are draft complete, apart from some intro and outro work that I need to do today. And I’ve got good chunks of the fourth and sixth chapters coming along, in addition to a growing number of topics for the fifth chapter, on interfaces and accessibility.

Put another way, this is starting to feel more like a book to me—and not just a collection of stuff I’ve written. Considering that the spring semester just ended for me a little over two weeks ago, I’m pretty happy with where I am. But I’m hoping to pick up the pace as I recover from this weird academic year and settle into the summer.

For the last few weeks, the brisk progress I’d been making on my WebRTC book basically ground to a halt thanks to my “day job” (as my development editor whimsically puts it). My day job is being a professor, and there’s really no worse time of year than mid-April until final grades get turned in. That period isn’t just about helping students over the finish line, but also accommodating a bunch of panicky colleagues and administrators scheduling last-minute meetings before people start disappearing for the summer.

Anyway. While I’ve not written much at all on the manuscript, I decided to take what time I could manage to work on my own organization, particularly all of the thousands of lines of source code I’m writing that’ll accompany the book.

Writing code for yourself or for your job is usually a bit different from writing code to teach others. Even the code that I write in order to teach in the classroom is different from code I write to accompany books and articles: my usual way of prepping for code-intensive classes is to do a dry run and then have skeletal notes or sometimes more complete examples to refer from, if I’m teaching something extra complex and am likely to forget some small but essential detail in the middle of class. I don’t like just walking through canned, finished examples in class: live coding is how I roll.

In an instructional setting, even if its online because of the pandemic, there’s always the chance to go back and fix something later or, in the best cases, improve something on the spot in response to a student question or point of confusion. Writing code live makes for a better class than a shitty slide deck with completed examples, I think, but it also helps students sort of wrap their heads around the timescales and especially the process of writing code. As every developer knows, the process is never linear.

But when you’re writing code for a book or an article, you don’t have the luxury of refining things once the piece is published. Throughout the writing process, you’re building a foundation and guiding someone down a path that you, as the author, will have finished before the reader even starts out. And that means that you’ve got to do a lot more planning, as an author and a developer, to figure out what the reader’s journey is going to look like.

To smooth the way for themselves, the authors of some books and articles—too many books and articles, I’ll add—basically set up the code equivalent of a straw person: early examples so amateurishly written and poorly formed that they’re basically laughable. Of course, just like the straw-person argument, it’s easy to swoop in as the hero-author and make yourself look amazing by fixing crappy, amateurish code.

I don’t like that approach, though, and I avoid it in my own work. And this is why: from years of both reading a lot of these books as well as teaching them, I can say that the first examples readers see tend to make the deepest impressions. I notice this in my own work, when I make a mistake that a book deliberately showed me and only then admonished me not to make. I see the same thing happen in student work too, either when they repeat a mistake that they were shown in a book or a mistake that I showed off in class before clarifying it as a mistake. That pattern is annoying for readers, too: Why did we just spend all that time talking about this thing that you should never do?

So rather than starting from crappy code, I like to start with reasonably good code—which, just like the running copy of anything I write, is never the code that I draft.

The trick I’ve found, and the thing I’ve been working on for the last few weeks with my book, is to write the absolute best code you can on your own. And then you dial it back a few notches from there. Maybe that fancy ternary operator has to go, or that little shortcut method or piece of syntactic sugar: anything that would take time and space too much to explain to readers, especially when they’re first starting out. It doesn’t mean that you won’t ultimately get the code whipped into that shape, but that you don’t have to start there—and leave readers feeling lost by all the ancillary, look-how-smart-the-author-is stuff that can wait.

I do think it’s useful, however, to point out common mistakes after walking through a piece of code—especially readers are expected to write it out themselves and run it. Beginners trying to pass a callback function in by reference in JavaScript, for a simple example, will very often include parentheses, so that the correct code on('event', callbackFunction); gets miswritten as on('event', callbackFunction());. It’s an easy mistake for beginners to make, because they’re used to seeing either the function definition— function someFunction() { } —or the place in the code where the function is called: someFunction().

The catch, of course, is when you as an author make a mistake in your own code. Alongside all of this, I’ve also been upping my automated testing game. (That’s included me bringing Nightwatch.js to the party. Testing WebRTC apps means having multiple, simultaneous browsers open for the duration of the test. Chrome can do that, but Gecko’s web driver implementation seems to be lagging somewhat. But this is all material for a whole other post.) Once I’ve got good-enough draft examples, I can’t help but continue to improve them. Sometimes the improvement is just about the code itself, but other times it’s about making the text read more gracefully. But even for books or articles, there’s no confidence in refactoring code without good test coverage. You’ve really not experienced BDD in full until you’re writing tests on code that you know will evolve a particular way over the length of a book.

One of the things I’m finding challenging about writing WebRTC code over a book-length work is that ideally the signaling and connection logic works completely separately and independently from any application logic. The application logic is what carries the examples throughout my book. At the same time, it’s too much to ask readers to write, say, fallbacks for older browsers in the signaling and connection code when they’re just getting started. So it’s necessary for me to keep track of gradual improvements to be made to the signaling and connection logic, even as I’m working through different examples with readers as they progress deeper into the book.

The latest strategy I’ve employed is to write the best, most thoroughly tested examples I can before I even begin to write a chapter. Then, as I write the chapter, I’m re-writing the completed example just as I expect a reader will. That frequently gives me insight as to the fancier or more complicated parts of my completed examples that I can save to guide readers through later.

So, that’s where I am. I’m ready to get back to churning out the running content of the book. And while I wish I had a few thousand more words to show for the last few weeks, I’m feeling pretty good that this code work is going to pave the way for me to better focus on how the book is put together—and how readers will work through it.

I went from not even realizing I was going to write a book to having a signed contact with PragProg in 82 days: December 17, 2020 was the first day I worked in earnest on the proposal, and March 9, 2021 was the day I received and signed the contract.

I’d only just submitted the proposal itself eight days earlier, on March 1. At 9:18am. I note the time, because it was just 28 minutes later that I heard from an Author Relations contact at PragProg with some of the best words a writer can hear:

You’ve done a great job with the proposal and sample chapter, so I think I can present your proposal without any revisions. It’s clear that you get the PragProg style and I’m grateful for that fact and happy to hear you are using PragProg books in your classroom!

(Yes, I use PragProg books in the classroom all the time, and no, I wasn’t ashamed to slip that little detail into my proposal itself.)

Since signing the contract, I’ve just been getting up to speed with Prag’s publication system—which I’m contractually bound not to discuss in detail, and I can see why. It’s pretty great. I’ve also begun working with my development editor, and I can say that this is book project is fixing to be whatever the opposite of lonely is. It’s an incredibly collaborative effort already, and I’ve only just gotten started.

Okay, but what about the book? What’s it actually about? Let me try out my elevator pitch on you:

You’re a web developer. You’ve spent the pandemic racking up untold hours on Google Meet, Zoom, FaceTime, or whatever real-time video-chat service. But what you might not know is that all modern browsers ship with an implementation of a web API called WebRTC: Web Real-Time Communication Between Browsers. WebRTC allows you to build real-time applications that run directly in the browser. And sort of like with FaceTime or whatever, you can build your own video-chat app. Only unlike all of those popular services, WebRTC works peer to peer: the app you build directly connects one web browser to another. There’s no server involved. And video chatting is only just the most obvious example. With WebRTC, you can open up channels to exchange any arbitrary data that might power all kinds of real-time activities: text-based chats, secure peer-to-peer file transfers, collaborative brainstorming sessions, and even multiplayer gaming. This book will have you doing all of that. And not just with two connected peers: an entire chapter of the book is devoted to engineering multi-peer WebRTC apps, using a mesh-network architecture.

Okay. So that needs some work. But hopefully the gist of it comes across.

So where did the book come from? Last fall, I taught a course on WebRTC for the first time. As I wrote in the proposal, putting that class together didn’t go very smoothly:

The biggest challenge I faced in putting together my WebRTC class over the last year was the lack of a suitable, up-to-date book for teaching or engaging in self-study of WebRTC—especially in the context of web development. As I detail in the competing books section below, there are a few rapidly aging titles on the market that are now little more than works of history. There is little, in book form or otherwise, that offers a substantial, pragmatic application of the WebRTC specification as it has matured since achieving Candidate Recommendation status in late 2017. (The spec became a full W3C Recommendation on January 26, 2021, while I was preparing this proposal).

Having scoured the web for as many articles and resources as I could to try to structure my class, I still had to write a lot of material for students—especially source-code examples. It was only after the fog had lifted at the end of fall semester that I realized I might have the material necessary to actually write a book about the topic.

It was really important to me to have the class structured around the native WebRTC APIs found in the browser, rather than rely on a third-party library. The book will be the same, native-API deal: although I’ll be using Socket.IO as a signaling server, all of the client-side code uses nothing but the available browser APIs (occasionally with an assist from the adapter.js to shim certain browsers as needed).

So that’s my news. I’ll be posting about the book here as I write it. And you’re welcome to message me about it on Twitter @stolleydotdev, of course.