Why should developers be the only ones who get to have fun with GitHub repositories? Writers can get in on the action too.
The point of this post is not to teach you how to use git and GitHub. You can find other resources to help with that. I intend only to explain why GitHub might be a good option for hosting Markdown files for cross-platform writing.
My digital writing workflow was straight forward as long as I was using only devices made by Apple (Mac mini, iPad, and iPhone) and could sync all of my Markdown files via iCloud. However, I ran into a problem whenever I re-purposed an old Asus laptop by installing Fedora 35, converting the laptop into a Linux desktop. (I call it a “Linux desktop” because the display no longer works, but the laptop projects onto an external display via the HDMI port).
I knew of no way for a Linux computer to sync with iCloud, so I had to look for a third-party syncing solution.
Following is a snapshot of some other options I tried before settling onto GitHub.
Technically, Dropbox could have worked–if I were willing to pay $9.99 a month (or $11.99 a month if I didn’t pay for a year upfront) for the Plus plan. But I didn’t want to pay just for syncing Markdown files. It’s not as if I have a huge library taking up gigabytes of storage, so anything more than $2 a month feels like a waste of money.
I could have stuck with the free plan if I were willing to limit myself to only 3 devices. But I instead chose to stick with my 4:
I also considered Dropbox Paper. While Paper does respond to some Markdown, I ran into a couple issues:
Paper didn’t recognize links written in Markdown. (What other problems would I run into if I used Markdown beyond headings?)
Paper doesn’t save files in Markdown.
I appreciate that Markdown allows flexibility for editors–I don’t want to be locked into a certain app or ecosystem. I write my Markdown files in iA writer on Mac and iOS. iA writer does not have a Linux client, so on Linux I use Typora.
Box & Google Drive
Box looked like a great option, especially since I have 50GB free due to some promotion from a few years ago.
But Box doesn’t have a Linux client. And using WebDAV has never seemed reliable to me.
I considered using Nextcloud to host my own cloud on a VPS like DigitalOcean or at home on my own Raspberry Pi. But I’ve been down that road before and know that I don’t want to be responsible for maintaining my own server.
GitHub to the rescue
After the failures listed above, I decided to give GitHub a shot. And I’m glad I did, because the process couldn’t have been much easier.
Using GitHub to host my Markdown files has required:
Creating a private repository for my files.
Using git for syncing the repository on the Linux desktop and Mac mini.
Using Working Copy for syncing the repository on my iPad and iPhone.
Perhaps I would not have been so quick to go with GitHub if I hadn’t already paid $19.99 for the Pro version of Working Copy. But the price of the Pro license is comparable to two months of Dropbox’s Plus plan, so this solution would still make sense.
Despite being happy with my choice of using GitHub, I would be dishonest not to mention some concerns with this solution.
Syncing is not automatic
Syncing via GitHub is not a big deal. Just execute a pull or a commit and a push, and you’re good to go. That said, I could forget to push on one machine and then jump to another machine, unable to access the latest version of a piece of writing on that original machine.
Fortunately, I’m not working on any mission critical projects. Worst case scenario, I might take my iPad to the coffee shop and be inconvenienced because I can’t access the latest file version I edited on my Mac mini or Linux desktop. That’s a risk worth taking.
This problem kind of plays into the point about syncing not being automatic.
What if I’m out of the house with my iPhone or iPad and do not have reliable internet, meaning I can’t pull and update from my GitHub repo?
While my concerns are valid, I am fortunate that I am hardly ever without internet or in a situation where forgetting to sync would be detrimental. Also, I am not currently working on anything critical that could not wait until a later date, even if my anxiety makes me forget that at times.
What if an outline weren’t a chore, but the first draft on your path to fine writing?
Recently, my technical writing class was discussing outlining, when I was surprised to discover how many of my classmates hate the practice. But I shouldn’t have been caught off guard, because I was in the same camp until only a few years ago.
Life before outlining
Sometimes you hear something enough that you can’t help wondering if there might be something to it. And so was the case when I heard that the key to good writing is rewriting.
The idea that great writers rewrite goes against our romantic visions of the wordsmiths we admire. We like to picture our favorite authors as able to sit down at the typewriter or laptop, clang their fingers on the keys for a bit, and churn out great stories with no sweat or profanity.
But no, that’s not how this writing thing works. You put some words on the page. You read over them and you scratch some out, and you move some around, and you fill in the holes in your prose until you hammer out something serviceable.
The wisdom about rewriting lodged itself deeper into my brain every time I heard it. And so began my acceptance that my writing needed a bit more work, opening the door for my eventual outlining practice.
I owe giving outlining a shot to a bit of writer’s block. I was stuck on a short story, unable to make the story’s events fall into place. So I put aside what I had already written and started working on a barebones outlining. By taking a step backward, I was able to move forward and finish the story.
While I don’t always start with an outline, I no longer avoid them as I once did. Outlines are the no-pressure way to start your writing project. You barf all your ideas into the outline, and you move things around or expand upon them. Or maybe you see that you don’t have enough material for your project and you move on.
No matter the result, outlining is a great exercise.
An outline is a first draft
I now see an outline as a first draft–a bland, dry first draft. The outline is a first draft focused only on the skeleton, the crucial elements.
The next draft is where you can sprinkle on the flavor. Perhaps it helps to think of the second draft as the creative draft.
Projects require no set number of drafts, but it’s a safe bet you’ll need at least one more pass for spelling, grammar, and general sense making. So that puts you at three drafts, with the outlining being the first.
What all can I outline?
What all does outlining work for? So many projects, including:
Basically, any project that benefits from clear communication is a great candidate for an outline.
“It’s like putting together a puzzle.” That’s how my buddy explained oil and gas abstracting. “Does that sound like something you’d be interested in?”
Yeah, I told him. I’ll give it a shot. I still had no idea what “abstracting” and “chain of title” and “runsheet” and “mineral ownership report” meant, but it all sounded better than selling cars in the middle of the financial crisis.
It didn’t take long to see what he meant by saying that my new job was like putting together a puzzle. And it didn’t take long to figure out that I liked the job. And now, all these years later, I’ve found myself asking why exactly title research resonated with me, because it wasn’t something I wanted to do before February 2008, when I first moved to Texas. Before then, title research wasn’t something I realized was even an option.
With oil and gas abstracting, the desired scene of the completed puzzle is always the same: You’re trying to get to 1. No matter how many owners under one tract of land, no matter how fragmented the interest–the final report should be whole. Complete. Like a jigsaw puzzle.
Through the lens of puzzle-making is another way to look at writing. Whatever we’re writing, we’re always checking to make sure that we have all the pieces. If we ever feel as if we do have all the pieces, then we have to worry about putting them in the right places. But when we do so, maybe we discover that we’ve put together a puzzle different from the one we had in mind when we started. Maybe the final picture doesn’t match the one on the box.
Complex title and mineral ownership necessitates a flowchart. I think of flowcharts as roadmaps that show where ownership began–usually with a patent from a state agency to the original grantee of the land–and the path it took to get to its current state. Writing is a bit like a roadmap too, starting readers at one place and then leading them somewhere else at the end.
Perhaps the biggest problem with this analogy is that our writing most likely never has all the pieces to make everything whole. Something is always missing. And if something’s not missing for one reader or audience, that doesn’t mean something’s not missing for another. Our projects will never be perfect. And we may reach the point of doing more harm than good if we keep cramming in more information at the expense of the flow or of our readers’ attention spans and patience.
But still, we have to try to get enough pieces. And we have to lay down the roadmap to show the proper order in which each piece needs to be experienced.
I entered college knowing only that I wanted to write for a living.
I had accepted that I wasn’t going to support myself on the paperback royalties of novels I would never write. Technical writing sounded unimaginative, and I’m not sure my university offered such a program anyway. Therefore, journalism seemed my only option, so I stepped onto campus as a journalism major. By the end of my first quarter, I had switched to Undecided, as I then had no idea what I wanted to do with my life, but journalism was not part of those future plans. Fast forward to 2021, and I doubt anyone would say with a straight face that I made the wrong decision. But I can say with the straightest of faces that I made the right decision for the wrong reasons.
I don’t remember much of my time in Journalism 101 other than I got an A for the course. In terms of writing, the most practical takeaway was to lead with a hard-hitting point and then follow with the details and backstory. I didn’t immediately realize how this method could also apply to fiction, the best example I can think of being the opening of Choke by Chuck Palahniuk:
If you’re going to read this, don’t bother.
After a couple of pages, you won’t want to be here. So forget it. Go away. Get out while you’re still in one piece.
There has to be something better on television …
Those opening lines may not have given me many concrete details about the story that followed, but they gave me enough to get the feel. And I was immediately hooked.
In my journalism course, I quickly discovered I did not want to engage in strictly fact-based writing with no obvious way to inject at least a part of myself into my writing. (I never claimed to be a selfless writer.) I had not yet discovered the likes of Joan Didion, Hunter S. Thompson, or Truman Capote’s In Cold Blood, though I doubt these discoveries would have made much difference, because I also left journalism for more practical reasons.
As I’ve already stated, I don’t remember much of the lectures from Journalism 101, but I do remember something I never experienced in any other entry-level course, which highlights one of the failings of higher education.
Every couple weeks or so, Dr. Blick welcomed journalists to share with the class their experiences in the field. The topics ranged from the humorous, as in the case of a now fellow alum whose typo in the school paper made its way to Jay Leno’s Headlines segment (She referred to a play version of Lean On Me as Leon On Me), to groundbreaking, as in the case of Leesha Faulkner, who uncovered the Mississippi Sovereignty Commission, a state agency dedicated to derailing the Civil Rights movement.
Despite the diversity in perspective and experience, I heard the same things repeated:
You work really hard. You have no security. You never see your family. You make no money. But it’s great.
I didn’t need to take on student loans just to be broke. After accepting I had no clues what I wanted to do, I tried my hand in computer science, only to crash and burn and then settle on a marketing degree.
In the name of being a real adult, I mostly abandoned writing, save for a handful of short-lived blogs here and there over the years. Within the last three years, I’ve started focusing on writing again, starting with dipping my toes back into fiction. I’ve studied the craft as I never had before, with a more open mind.
I’ve now read books on screenwriting and have marveled at how much a screenwriter must convey with so few words. Previously, I didn’t realize how much the writer directs certain details, holding everyone’s hand in the process.
Studying copywriting is another study in communicating efficiently. The best slogans are simple. They require no explanation. They’re like jokes: If they require explanation, then they’re not effective. You remember effective slogans because they slide off the tongue and have a certain rhythm. These are some of the reasons the most nonsensical song lyrics can lodge themselves into our brains.
From studying technical writing, I’ve learned the values of knowing when to holds readers’ hands and when to squeeze tightly. I now see that a career of explaining complex issues in oil and gas title has taught much of the same. And I’ve also learned that most people who say they don’t have the time to hold someone else’s hand through an issue most likely lack the knowledge and awareness of how to do so and also have no desire to learn how.
I’ve been asking myself recently what is the strand that ties all writing together. What is the one similarity? The unifier, other than a need to communicate?
And, as we speak, my answer is: persuasion.
The angle of persuasion is obvious for some fields, such as legal writing, in which briefs are intended to persuade a judge to rule in a client’s favor. Sales copy aims to persuade you to make a certain purchase. Business emails persuade recipients to act–or maybe they persuade that no action is needed. Even research papers should aim to persuade, as we don’t have to look too hard around us to see that facts alone are not enough. If nothing else, I have to persuade you that my facts are more accurate than your facts.
But what about fiction? Where’s the persuasion there?
In fiction, authors are trying to persuade readers that this fake world with these fake people in these fake scenarios contains some sort of truth worth their time. Authors want to convince readers that this person in this situation would act or feel a certain way.
And sometimes the persuasion takes a different angle, such as in the case of some of the best tellers of tall tales, the ones who stretch the truth–or, in some cases, discard the truth completely–and leave us doubled over, hoarse from laughing through the tears. Sometimes writers persuade us not to care about reality so much.
I know I have few–if any–original ideas, but I recently realized that the point of this post isn’t original even in regard only to my thinking, as I shared the picture below in a previous edition of Emergency Coffee, my monthly writing newsletter:
In the past, I abandoned writing because I failed to see the similarities among the separate disciplines. I also failed to see that there is no down side to being a better writer. Even if you never make a penny directly from your writing, the thought and effort required to improve as a writer likely benefit you in less obvious ways.
Now, if I read something as mundane as the back of a shampoo bottle, I no longer brush it off as an irrelevant form of writing. Instead, I wonder why certain things were done certain ways and then ask if or how my own projects could benefit from those methods. This way of thinking makes me a more open-minded writer than I was when I set foot on that university campus all those years ago.