Lately I’ve been focusing on refining the content on my API documentation site. I’m trying to finalize the content to publish the material as a Kindle book and a downloadable PDF. As part of the content refinement, I’ve been updating tutorials, screenshots, and other information. I’ve been fine-tuning the organization and sequence, assessing and adjusting content, and most of all, editing, editing, editing. During this time, I haven’t been writing much new content (other than the OpenAPI tutorial, which I already mentioned last week).
Overall, I’m feeling pretty confident about where I’m at with the content. For the most part, I think I nailed it in terms of what I’ve chosen to cover and write about. My goal is to finalize the book by the end of the year and then start on a new one.
As part of the publishing process, I’ve created a publishing channel to push the content from my Jekyll project out to both PDF and Mobi. Mobi is the primary format Kindle uses. I’m actually quite excited about these outputs. Writing the content in Markdown/HTML, particularly using Jekyll to package up the site, and using CSS for the stylesheets, gives me a tremendous amount of control.
My next project might be to package up this Jekyll theme and document it so that anyone can use it to publish to PDF or Kindle outputs. Kindle in particular is tricky because there are quite a few adjustments I had to make (some CSS properties aren’t supported, I needed special section pages and a navigation index, and such).
I feel like I’ve cracked the code on how to output to these other formats (Kindle in particular), and now I can channel my writing energy towards ebooks, bundling up posts into longer works. This is something I’ve been wanting to do for a long time.
I’m not quite sure when, but for at least the past year I’ve grown tired of the one-off nature of blog posts. I might sink hours into writing a really thoughtful blog post. When I publish it, the post gets a lot of retweets, likes, and comments. But in two weeks, the post slides into oblivion. I have to crank out new content on a continual basis, only to see the post start fading the minute I hit publish.
I’m not sure if Google sets the half-life of a blog post at two weeks or something, but it doesn’t take long for the post’s fire to smolder out and become gray ashes. Blogs are ultimately like news. Perhaps blogs should really be like little notes on larger projects you’re tackling, not the projects themselves.
I do think blogging can be a tremendous tool for incrementally building out longer content, and that’s how I’ve tried to redirect my energy. Blogging allows me to publish larger works of content step by step. No one can write a book in an evening, but you can certainly crank out a blog post in an evening. Multiply that same evening effort over a year, and all that blog content could be orchestrated and consolidated out into a book, assuming you’ve been writing in a consistent theme. At least that’s the idea and my vision for my blogging effort in the long term.
But these last few weeks, where I’ve been heads-down focused on finalizing my API doc content, I’ve realized something. Although I certainly see the value in editing, if I spend all my time editing and revising, I lose interest in writing. My favorite part of writing is creating new content. I like filling a blank page. It’s as if I have an unlimited supply of creative energy inside me, waiting to find its way into newly crafted posts and essays. If you’ve been following my blog for the past decade, you’ve no doubt seen this energy come out in post after post.
Many people start out blogs with endeavors to sustain it in the long run, only to find that they lack long-term interest or energy for it. But for me, creating content is my strong point. What isn’t my strength is revising and editing existing content over and over and over until my eyes get bleary and I get sick of reading the content — so sick of it that I just want to hit Publish and move on.
I do edit what I write – don’t get me wrong. I may read a post 10 times or more (especially spaced over several days) before publishing it. But here’s what I’ve realized: Writing is a steady balance of three activities:
Pretty much in that order, and pretty much in even parts. For example, to write a good post (or article or page or essay), you might spend 3 hours learning, 3 hours writing, and 3 hours editing.
Writing tends to differ by person, so it’s hard to say whether this balance just fits my own style and brain or whether it’s more universal.
Also, it might not be necessary to focus all three activities on the same topic. I might spend a few hours editing my API doc content, a few hours writing a blog post like this one, and a few hours learning some technical topic at work. It’s the balance of the three activities that’s important.
Compare this trio of writing activities to a triathlon. An athlete spends some time swimming, biking, and running. Few athletes could complete a triathlon if it involved the same activity merely repeated 3 times (imagine the joy of a 26-mile run followed by a 26-mile run followed by a 26-mile run). No, it’s the switch to the other activities that use other muscle groups and movements that allows athletes to continue forward with such endurance. Same with learning, writing, and editing.
I know this may seem like common sense, but for me it has been somewhat of a revelation. I was telling myself that I wasn’t going to write anything new until I finished my API book, but two weeks into the effort, I started losing motivation because I wasn’t writing and producing content like I’m accustomed to doing. I wasn’t learning new content. I was just editing, editing, editing.
Switching activities may initially appear to take me off task, but in the long run, it will give me the energy to complete the race.
I’ve used editing as an example here, but if I were to focus solely on the other tasks, such as just learning or just writing, I would have the same result. Almost no one, not even successful fiction writers, sit down and write non-stop all day long. I think most writers spend about 3-5 hours a day writing, max. Some spend even less. There’s only so much one can say. It doesn’t take too long to empty my brain out, and then I need to refill it again by learning some new thing.
After writing a few hours, I may have some good ideas on the screen, but they’re usually messy. The ideas need refinement, re-organization, more detail in places, less detail in others, and so on. The editing mode needs to kick in, but not forever.
No doubt different areas of my brain are active during these three separate activities. The left-brain/right-brain dichotomy has been exposed as a myth. But I’m fairly certain that each of these three activities (learning, writing, and editing) tends to light up a different patch of neurons.
We tend to like graphics, so I’ll end with a simple graphic here:
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. In this blog, I write about topics related to technical communication — Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, academics, and more. I'm interested in , API documentation, visual communication, information architecture and findability, and more. If you're a technical writer of any kind (progressional, transitioning, student), be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.