Giterary outright steals most of its good ideas. Maybe all of them. But that’s sort of what building software is all about. You see something, and you say, “Hey, that’s neat, but it doesn’t do X.” And you either live with it until something better comes along, or you hack something together yourself.
An idea that I stole from the coding world is TODOs. A TODO is a special comment in code that indicates to a later programmer that something remains “to be done” in the code, but works as-is for now. For instance, see here in the Giterary codebase:
// TODO: Label manipulation to allow for
// matching highlights.
ret.push({
label: value,
value: value,
weight: weight
});
regex.lastIndex = 0;
(Code here)
The TODO in the comments above gives the programmer something to come back and search for when looking to making improvements. That, or to fix something that had to be left behind for higher priority issues. You use the word TODO rather than TO DO or TO BE DONE because there is no word ‘TODO‘ in the English language, and it’s unlikely that it will appear naturally. This means that it’s easy to search for the string ‘TODO‘ in your source code.
We use the same convention for our novel writing. We use TODOs pretty extensively. Often, there will be something that either:
- We need to research more thoroughly, or…
- We don’t have time to do said research, or…
- We have to rely on the other person to answer a question or get feedback.
You don’t want to forget to come back to the section, but you also don’t want to waste the precious little time you have. There are only 45 minutes you have before the yoga moms get out and start hogging the cafe WiFi while their miserable children run amok. So, rather than losing your place and your flow, you just put a ‘TODO‘ into the text and promise to yourself to revisit them periodically.
At time of writing, we have about two hundred TODOs left to resolve and document. This is down from the nearly four hundred we had before. Here are a few choice examples of our TODOs, littered among the chapters and marginalia of our repository:
TODO: Lighthouse(because we like to have the notion of a lighthouse at every sea or sky port)Religion - TODO Polytheism(because we are bad at naming things)BE —400 Kingdom of Cail founded by the TODO family.(again, bad at naming things)TODO: Consider a chapter break here(because we write marathon chapters and need to split)
As we get closer to publishing, we are also treating the presence or absence of TODOs in a document for whether something is worthy of publishing. If something still has a TODO, it requires some degree of modification before sending it to an editor. However, if the TODO is something more like, “Remember to include this later when you write this part,” we actually call this a ‘Callback’ or CB. TODOs and CBs in Giterary are exactly the same. We just treat them each a little differently in our workflow.
So, TODOs are messages embedded in our writing. Messages to remind us of something. Messages to keep us anchored where otherwise we might forget something. Messages to each other. And messages to ourselves from the distant past.
They’ve got their problems, though. A few we’ve come across:
- We’ll forget what the TODO is about.
- We’ll disagree with the TODO after enough time has passed.
- More work is spent talking about resolving the TODO than is actually spent resolving the TODO.
Take for instance something from earlier this spring (Spring 2016). I added a TODO as a hidden comment to the end of this paragraph at the end of Volume 1.
The second attacker hit the deck running and skidded to a halt in front of Vasili. The boy found himself frozen in terror, his eyes locked with tinted goggles. The man’s mouth split into a savage grin full of yellow teeth and he raised his sword. Driven by instinctive reflex, Vasili found a surge of energy and kicked at a plank. The piece of wood skidded across the deck and took the goggled man by surprise, catching his toe and making him stumble. Before Vasili could regain his own footing and make a run for it, Hash was there, his sword spinning in the light. Like in the tavern, there was not much of a sword fight, only a single off-balanced parry and then the quiet man’s blade was cutting through the attacker’s stomach.
JAR: TODO We should talk to choreograph this out. As is, I'm a little confused.
I hit commit and walked away. I find that if I go and do something else while I’m thinking through a problem I can focus better. I was busy preparing for the ritual of my yearly car wash. I don’t know what Mike was doing. But I got a text pretty quickly after.
Mike: I'm curious what you find confusing about the Second Attacker in Consequences.
‘Consequences’ is the original name of one of our chapters. They have all since been split and renamed, but we still refer to them by the original names.
Josh: How does he kick the plank such that it trips a guy? Particular a guy who just came down a rope and landed with a sword in hand.
I worry a lot about details. This was one where I thought an unfinished piece of wood wouldn’t slide very well, even on a polished deck (and the Break’s deck is not polished). A kicked ball would have a time getting across the deck. Friction would be a problem.
Mike: Maybe stumbles is a better word. Even if he jumps it, it buys Vasili five seconds of life for Hash to rescue him.
I agree with Mike. My TODO just reflected that the recent edit didn’t work as intended.
Josh: Thinking that the wood is heavy, and would just slide across the deck with plenty of time for 2nd to lift a toe and stop it. Maybe that's it? It's just a distraction?
Mike: Also, he's wearing goggles, which might limit his vision.
I try to clarify, my hands wet with soap, water, and chamois, challenging the degree of water proofing that was done on my phone.
Josh: I'm just not seeing Vasili Jackie-Chan-ing a plank. I'm seeing him do something odd and confusing the attacker.
Mike defends his edits.
Mike: I just don't think it's necessary to describe anything further. He does something and it's effective long enough to save his life.
Maybe he throws his axe, perpendicular to the guy, as if one would say “catch!” And toss an implement to a friend.
My neighbors keep looking at me as I start to spray down my car, then stop, text, realize the car is already drying, and then start spraying again.
Josh: Nah. Vasili is scared shitless, how would he come up with that?
And then the juice, the description and inspiration behind what Mike intended with his edits.
Mike: He's scared, but it's that part of the brain that just reacts. Not calculated, otherwise he might take a swing.
Same with the kick of the plank. it's like you just react with what you are given.
When I scared my friend Pat with my tshirt over my face and a butter knife, he uttered some guttural gasp and gave me a rabbit-punch to the chest
I guess as a contention to that point, Vasili has done nothing in this fight, and by giving him a redeeming quality other than chopping at the lines, our readers might empathize with him a modicum more.
So I don't think it's a Jackie Chan plank elevation kick to the gut, but a “fucking shit I'm going to lash out with whatever I have”
And this 2x4 skitters over the deck and the guy slips on it, or jumps it, and is distracted long enough.
Josh: Can we never decided book stuff over text? We're talking about the same thing.
Plank is distraction.
Mike: Can we exclusively talk about book stuff over text? I want Vasili to cartwheel-grab this guy by the neck and fling him overboard Xenia style.
Then drop into a cautious crouch.
Josh: I quit.
Don’t let this be you.
I include the above conversation to show how not to communicate. If something is confusing, I guarantee that text messages will compound the issue.
Find some way to provide consistent communication, as well as choose a medium that lets you review past decisions. Email chains, Slack instances, or something like Giterary that will track TODOs go a very long way, as they have features that allow your messages to become documentation. SMS messages, and messaging schemes like it, do not. They are intended for quick, throwaway communication that has no expectation for long term storage, search, or retrieval. Phones die, and text conversations get archived and deleted.
As an author, it is your job to communicate ideas clearly and unambiguously to your readers. As authors, plural, you are doing the exact same thing, but in addition you are communicating directly to your co-author. Your communications between each other are just as much documentation as your notes and sketches. Having a system like the TODOs certainly helps, but being mindful about the nature of your communications is just as important. As Mike can attest, I’ve now quit the book a half dozen times, facetiously or otherwise.
Finally, if you do end up using TODOs in your work, please heed my advice: make sure that your notes surrounding your TODOs are clear. It might be next week that you fix that TODO. Or it might be four years later. But nothing keeps you up at night wondering what you meant by TODO: “Come on, son".
In this way, the workflows of novelwriting and computer programming are much the same. You have large collections of text documents that must be continuously updated and maintained. You might not have the immediate time, energy, or interest to solve all of the problems that you come across during your writing/coding sessions. But you will over a long enough period of time. The problem is the writer/programmer forgetting something.
Each word of a novel is part of a machine with a few hundred thousand moving parts. And you, as the writer or the programmer, are the flawed, squishy pulp with a small short term memory and a faulty long term memory. You can’t possibly remember each piece, each intention. Or even if you do, you may no longer have a handle on whatever emotional truth you were trying to convey. I can say for certain that we didn’t remember all of our TODOs when we came back to them. Some we had to give up on, and be content to assume that it must not have been that big of a deal to begin with.
In doing some research for the book, I read about super long-lived trees. I found that, depending on the size and age of a trunk, the innermost parts of a tree trunk are actually dead, having succumbed to age or decay. The wood material remains, providing structure to the tree, but the living part is only a thin layer towards the outer edge of the trunk, growing bark and more tree rings as the seasons march on.
To some degree, writers and our projects are just the same. The author is the thin part, just beneath the bark, that grows it outward.
Here is the latest version of the paragraph (with modifications underlined):
The second attacker hit the deck running and skidded to a halt in front of Vasili. The boy found himself frozen in terror, his eyes locked with tinted goggles. The man raised his sword, readying to attack the boy. Driven by instinctive reflex, Vasili found a surge of energy and kicked at the end of a plank. A distant pain came from his toes. The heavy board slid across the deck towards the man, slowing to a disappointing stop as it nudged the heavy boot. The man looked down for a moment, perplexed, then his mouth split into a savage grin full of yellow teeth. A blade spun in the light. To Vasili‘s relief, the momentary distraction gave Hash what he needed. Like in the tavern in Schultzwald, there was not much of a sword fight. A single off-balanced parry and then the quiet man’s blade was cutting through the attacker’s stomach.
No telling if all this effort makes an improvement, but eh. On we go.
