Don Jones®

Tech | Career | Musings

I’ve recently had a few pings on Twitter from folks asking me how I write–everything from general questions to specific questions about Leanpub.

Here goes.

Writing in Leanpub

I love Leanpub. It’s an Agile writing platform that also does a damn fine job of letting an author monetize their work. They offer the fairest customer policies I’ve ever seen, and they’re easy to use.

You first decide where you want to keep your manuscript. I use GitHub; it makes collaboration easy, natively understands Markdown (which is what Leanpub uses, either “Leanpub-flavored” Markdown or their own superset called Markua), and GitHub obviously tracks changes pretty well. But you can also use Dropbox, Bitbucket, or other “sources.” And it’s relatively straightforward to switch a book from one to another if you change your mind. In GitHub, you can use both Public and Private repos, and you simply invite the @Leanpub user to be a Collaborator in the repo.

Whatever you use, your source must contain a root folder called /manuscript. This is where your manuscript goes. Anything else in the root can be notes, whatever you like, but Leanpub will ignore it.

A file named /manuscript/book.txt is mandatory. It’s just a list of filenames, in order, that comprise your book. And the rest of /manuscript is simply those files, all plain-text, and all written in Markdown.

If you’d like to see what this looks like, check out the public PowerShell by Mistake repo, and you can see the full, raw book layout.

When you’re ready to preview your book or publish a new version, you do so on Leanpub’s website (they support auto-publish triggers from GitHub, but I tend to commit as I write and only publish when I hit certain milestones, so I don’t use the triggers).

Leanpub lets you set pricing, coupons, and a lot of other financial options. They take care of sales, handling customer returns, etc. And, if your book gets picked up by a “real” publisher, you simply “retire” it on Leanpub. You own your copyright, and so you can take it off the platform at will.

Need a print book? They’ll export an unbranded, print-ready PDF or EPUB to make your life simple. They support a huge range of book sizes, so you can pick one that meets your specific needs. The print-ready PDF can include an ISBN if you have one, and does not include cover art, which printers usually require as a separate file. I use Amazon’s Kindle Direct Publishing (KDP), which does paperbacks in addition to Kindle books and is replacing the company’s CreateSpace offering.

Sidebar: Amazon has a lot of evil in them when it comes to authors, but they’ve essentially made themselves the only game in town, so you go to where the action is.

The Leanpub Manual is straightforward and explains everything in very good detail, including all their specific Markdown variations that are specific to book publishing.

There’s a small investment to use Leanpub, in that you have to pay for a plan that includes a certain number of books, a certain number of “publish” runs per day, and so on. This is because it costs them money to run the platform. Once your books have earned a certain amount of money, the plans get cheaper and/or free, include more books, unlimited “publish” runs, and so on.

Need to know more? Post a question in the Comments!

Writing

The first two years I was a freelancer, I wrote 6 books a year. Big books. Like, 600+ page tech books. I’ve definitely got a system that works for me, and it’s worked well, so I stick with it. But that doesn’t mean it’ll work for you. So take all of the following with appropriate doses of sodium.

The Outline

I outline extensively. For me, sequencing material is critical to getting a good book out the door, so I will spend all the time I need making sure I’ve got a solid outline, down to 3rd level headings. I add copious notes so I don’t forget what I meant, and so I’m documenting everything I plan to cover and the order in which I plan to cover it. People who just jump in and start writing, in my experience, tend to produce a poorly sequenced book. Outlining might not seem like fun, but it’s where all the actual effort occurs. With a good outline, you just need to write a few paragraphs for each third-level heading, and you’ve got a book.

Good outlines prevent writer’s block. They give you the bones of a schedule to write to. They’re the basis of good writing, for me.

Audience

I think a key to good writing is writing the book your audience needs, not the book you want to write. My first PowerShell books were structured like my VBScript books had been, which meant they were programming books. My first PowerShell audience consisted of VBScript people, and that’s the book they wanted and needed. But later, as non-VBScript folks started coming into the audience, that changed. They didn’t want to approach PowerShell first as a programming language, yet that’s where all the books on the market were. So I designed Learn Windows PowerShell in a Month of Lunches, which you’ll notice has zero “programming.” That’s why it’s successful. I took the time to design something the audience could work with, rather than just writing the way I personally thought about the topic. Instructional Design for Mortals encapsulates a lot of those learnings, which actually involved a good amount of research. Like: when you’re writing a chapter someone needs to read in under 45 minutes, how many words can you write without going over?

Nostalgia

I find it’s sometimes difficult to remember how I learned something. What “threw” me when I was getting started? What analogies would have helped me better understand things back then? I feel too few authors take the time to go back in time, and remember what it was like to not know. 

There’s a common misconception with writers and other teachers that their job is to present things to the learner in a way that keeps the learner from failing. You line everything up just so, so you create a safe and perfect journey. That is not the case. Teaching is an exercise in sharing your failures, in packaging them so that you can present them to the learner, let the learner face them, and then guide the learner past them. Humans learn through failure: it’s how our brains are built, and you can’t bypass it. So you have to remember how you failed along the way, and present those failures as experiences for the learner. You’re not preventing failure; you’re accelerating and guiding it.

Writing fiction? The same concept applies. I’ve found that I needed to go back to books I’ve loved and re-discover what I loved about them. Was it the world-building? The dialog? Something else? That lets me focus on those elements in my books, making them something that an audience similar to me might love.

Sequencing

When you’re trying to teach something, whether in writing or any other way, proper sequencing is essential. You can’t effectively learn multiplication without first understanding what addition is! Each chunk that you write or teach should build on what just came before it, and open the way for what will just come after it. Ideally, every chapter should conceptually wind up with something like, “and now I’ve shown you how to do x. But an obvious problem with what I’ve done is y. And so let’s get into that in the next chapter.”

I try to never foreshadow in teaching. I try not to allude to things I’ll teach in the future, because it can create anxiety or a rushed feeling for some learners. I cover each thing as I come to it, and no more. If I get to topic A and I can only cover part of it, because the learner also needs to learn some of topic B to go further, that’s fine. I’ll cover what I can now, get to topic B in sequence, and then circle back to topic A and fill in what I’d skipped the first time. You didn’t learn All Of Math in your first math class, right? So you don’t need to teach All Of The Topic in the first encounter, either.

Foreshadowing obviously has a place in fiction, but you have to use it very judiciously, or it gets worn out quickly.

Scoping

Human brains can physically only learn so many new things at once. You can’t change that; it’s in our basic biology. So it’s your job to chunk the material into pieces a human being can handle, and that means you’re going to have to make choices. The same concept applies to fiction, although since you’re not “learning” per se, you’re dealing more with attention span. There are a reason things like “chapters” exist in the world, and a good author uses them effectively.

You will not be able to teach All The Things in one go. Figure out what will fit your reader’s attention span and biological capability, and then triage. Teach what you can, knowing there can always be other chapters, later, that teach more. Use chapters to break material up into discrete pieces that are well-sequenced, and you’ll have a good book.

Do not go off on tangents. I hate tangents. “Oh, I just need to quickly explain this one caveat…” No, no you don’t. You do not, repeat not, need to teach Everything About The Topic all in one go. It’s actually fine to smooth over some rough details in the beginning, and then circle back later to dig into them more.

For example, PowerShell has an insidious command called Write-Host. Newcomers latch onto it like a teddy bear, and wind up going down some very dark and confusing paths as a result of how the command actually works. So I make them write down, “Every time you use Write-Host, God kills a puppy.” It’s a snarky, big-sized statement that gets the point across. Later, after we’ve gotten more important things out of the way, I can circle back and explain what Write-Host is, where it’s actually useful (a small number of cases), and so on. What I don’t need to do is take a fresh, short-attention-span learner, and immediately subject them to a detailed analysis of Write-Host that won’t even make sense because they lack the broader context in which to place it.

As a child, one of my favorite book series was Children’s Illustrated ClassicsThese are massively pared-down, illustrated versions of classic novels. They skip almost every tangential plot line and focus only on the main plot and characters. It’s a way for a young child to grasp the main story. Are they “literature?” Maybe not. But nothing stopped me from going back, as an older child, and reading the “real” versions of those novels. I got to get an early exposure to wonderful stories that I never would have ventured into at that young age, but I still, in the fullness of time, got the “whole story.”

Preparing

When I get ready to write, it starts in the evening before I go to bed. I throughly read the outline for the bit I plan to write the next day – this applies to my fiction books as well – and then I go to bed. My brain does brain things, and I wake up the next morning fresh and ready to write that chapter. I can knock out around 5,000 pages words  in a couple of hours, most times, following that process. I do not write past what I’d pre-read, ever.

If what I’m writing is feeling like crap, I stop. I go do other stuff. That evening, I repeat the process: read the outline, go to bed, wake up, try writing. That usually loosens things up. That “block” usually happens because my outline wasn’t put together very well, and my brain needed some extra time to come up with a narrative that worked. I don’t dwell on it, because I know my brain will come up with something.

Sometimes, it might mean stepping back from a chapter and writing the next one, or the one after that, and then coming back to it. Sometimes it means I’ll find a flaw in my outline, and the “block” is my brain’s way of saying, “please don’t do this to me.” So I’ll rethink the outline, review what I’ve already written to ensure it’s consistent with the new outline, and move on.

The Voice

One reason writing comes easily to me is that I never went to college, never went to a “writing class,” and was never taught that writing has to be done in some stilted, formalized, passive, third-person form of language. I write, more or less, like I talk. Mind you, I speak fairly well and have had a great deal of practice doing so, which definitely helps. But I don’t write sentences like, “now we will see how the computer is configured by that means.” I’d write, “now you see how you configure the computer.” You. I. You are doing the thing, versus “the thing has been done.” If you write like you speak, the words flow more naturally, because it’s what your brain is accustomed to doing anyway. This entire article, for example, took me about 45 minutes to write, and that included drinking a smoothie and getting a fresh cup of coffee. The speed mainly comes because I can’t type quite as fast as I talk, so my brain has plenty of time to form the sentences as my fingers are struggling to get them down.

I Hope That Helped

I know this is only about 2500 words or so, but I feel that these are the key things I had to really learn over the past 20-odd years, made as concise as possible. I do suggest reading that instructional design book I linked above, as it has a lot more. It’s still very concise and very easy to read.

Not incidentally, I’d actually love to do a writing workshop for technology writers sometimes, but I refuse to do it remotely because I feel it’s something that’d be much more effective in person. If you’re interested, drop a comment, and I’ll keep it in mind. Maybe connected to a large event where people tend to go anyway would work out.

If there’s something more I could add to this, please drop a comment. I’m happy to do so.

3 thoughts on “How I Write

  1. Alex says:

    I have no interest in writing something, but yet I found this article fascinating, fun to read, and extremely well written! Thank you Don for sharing your knowledge and process.

    Like

  2. davejdyer says:

    Great article! I’ve been ramping my brain up to try my hand at writing something substantial like a book or even just some consistent blogging. I’ve read Instructional Design for Mortals, and I’ve begun internalizing the need to do outlines but the idea of focusing on that one day before bed and hitting the actual writing the next is golden. My biggest roadblock has been scheduling myself. I think this idea will help me get into a rhythm, and I’ve already noticed that I my thoughts fire more quickly first thing in the morning. It wasn’t always that way, but you know.. Age. Thanks, Don. I really appreciate you continuing to share your experience.

    Like

  3. Joe Houghes says:

    Great article Don, just re-read this while reviewing my success criteria and working my monthly plan for the Masters program. I’m reading through Instructional Design for Mortals to try and help me define what medium is the best for my brain to be able to best create instructional content that is actually usable by people.

    I’d absolutely love to attend the workshop for technical writers if it becomes a reality.

    Like

Comments are closed.

%d bloggers like this: