I don’t know that I’ve ever really gone over my writing process and/or tooling here but I’ve recently come to a new thing and think it’s pretty fun and so I thought I might share. So I’m sharing.
As is frankly probably not always clear from this particular #blogsite, whether because I don’t talk about it or else I don’t really write posts very often, I do a lot of writing. I write professionally doing technical writing and I write as an amateur at fiction. And having done this for, you know, a while, I’ve had the opportunity to play with a lot of different tool sets. I think the first “Novel” I wrote (in the 5th grade) was in ClarisWorks (a precursor to AppleWorks, remember that?), and since then I have used everything from MS Word to Scrivener to a variety of code editors (about where I’ve landed now).
My tooling has always changed depending on what I was working on, where and when I was working on it, and what I was aware of. I like learning new tools and so will often do a project in a tool just for shits and giggles, just to figure it out.
A Brief Note About Binary vs. Plain Text Files
Binary formats (e.g., doc, docx, photoshop and in design files, etc.,) are great for a lot of things. But ‘plain text’ formats, like txt, md, adoc, etc., are also great. Since they don’t have any formatting information, the files are very small. It also means that they can be opened by pretty much any computer, EVER. This makes them supremely portable, and not locked into any programs in particular, e.g., MS Office or Adobe products, which you typically have to pay for. Plus, given my life as a technical writer, programmers will always be able to open a txt file; they are less likely to shell out for MS Word, and though Open Office is GREAT, the formatting transfer from one to the other is less than desirable. I’ll talk more about formats below.
Of course, the canonical tool has been and will continue to be (at least from a sending-to-other-people point of view) MS Word. It’s ubiquitous, somewhat powerful depending on what you want to do, and more or less something that everyone and their mother/brother/sister/father/grandparent can open and read. That said, fonts are distracting, options are distracting, and I am prone to distraction. That was why (in addition to not wanting to pay for the early and frankly shitty mobile versions of MS Word) I switched over to more “focused” tools at some point in college, specifically iA Writer, which I still strongly recommend for a lot of folks, and still use pretty often.
BUT!
Now I think I’ve found something I like quite well. And so I’m going to talk about it. But first…
The Old, or Tools That I Have Used
Here is a roughly chronological list of tools that I have used, why I liked them, why I didn’t like them, and why I moved on to something else.
MS Word
I’ll start here. As I mentioned above, I’m still using this from time to time, but I do my best not to actually do my writing in MS Word. I like to do formatting and styling in MS Word, but actually writing in Word, especially now having worked primarily in more writing- and text-focused tools, it just doesn’t really do the trick.
Pros:
- Ubiquitous, familiar, what most journals, bosses, and other applications prefer so far as file type.
- Pretty powerful, styling wise, if you know what you are doing
- Track changes are actually really great, once you’re at that point.
Cons:
- REALLY FRUSTRATING if you are inheriting a document and they fucked up the possibly powerful styling tools and you have to go through and reformat it (I realize this is more of a personal problem, but this simply isn’t possible if you’re just using plain-text formats).
- Versioning is basically a nightmare. This makes collaborating over time a PITA, even if Track Changes is a great thing.
- The WYSIWYG element is great sometimes, but other times is distracting.
Why I Stopped Using this Tool:
There are better options for actually writing so far as I’m concerned. But like I said, I still use it for finishing/formatting/as a format for sending to other people.
iA Writer
iA Writer was fucking great for a long time. Still is, really. I got it originally because it was an early good syncer on iOS/Mac (my hardware setup), it was writing-only (i.e., no formatting options), and was kind of a “thing” for a while. I started using it in college, which was also when I admit I was doing some drafting on a manual typewriter which I’d bought at a flea market back home in St. Louis, and the app mirrored that, had typewriter scrolling (i.e., the line you’re working on stays in the middle of the page), and a focus mode (which would let you only really “see” a word, sentence, paragraph, etc.). All great things.
Pros:
- Clean, solid writing environment.
- Worked with markdown/plain text files.
- Outputs well to MS Word, HTML, etc. Has customizable style sheet options.
Cons:
- iCloud syncing sometimes fucks up (this is not a problem with iA Writer necessarily, but a thing that irks me; I have also lost work due to this).
Why I Stopped Using this Tool:
I still use it, but not exclusively. Mostly because though it’s amazing on the iPad/phone, on the Mac it’s like, “OK,” you know? Very good, but not so stand-out when compared to other options. It’s something I like to use sometimes, when the mood strikes, and I used to use it to turn markdown files into Word files, but I’ve got a better solution now (read on for more!).
Brackets
Brackets is actually a web-focused code editor which has been picked up by Adobe. It’s free, worked reasonably well while I was using it, but at a certain point started crashing, and none of the developers I knew used it, so I started using what they were using, Atom, below. So far as actual writing, it was a text editor! This had certain benefits, and certain downsides.
Pros:
- Because it is technically an IDE (development environment), I can have this app open at work! Writing at work is great.
- Good support (with plugins) for various markup languages (I was using Markdown).
- The file browser can be nice if you’re working on a project with multiple files (e.g., blogging!), but I didn’t have a good way to work with multiple files for fiction projects until Scrivener (below) and then my new solution (also below), so this was kind of moot while I was using the tool.
Cons:
- It’s a code editor, not a writing tool. So, you know, it’s not really a writing tool.
Why I Stopped Using this Tool:
My developer buddies were using other tools, and thinking someday I might get a web dev gig, I figured I would learn the other tools.
Scrivener
Ah, Scrivener. I would prefer not to and all of that. Ubiquitous at AWP, and a sure-fire way to tell if someone in a coffee shop fancies themselves a writer. I had been reading about this for a long time, but a friend of mine (the very talented and wonderful Ali Lanier) swore by it, and since she was easily one of the most prolific writers of my friends, and she worked on big, complex novels, and I was starting to work on a bigger, more complex thing at the time, I figured I would give it a go.
I wrote a lot of the first draft(s) of my MFA thesis in Scrivener, feel like it works pretty well, and honestly I’d recommend it for a lot of people in a lot of circumstances.
Pros:
- Powerful. I didn’t use nearly all of the things that it could do, but I appreciated that it was option.
- The editor is really good. You can turn a lot of things off and on, make it bigger, smaller, focus modes, etc.
- One of the best single-app multi-document solutions I’ve ever used in a writing-focused app.
- Can output a lot of different kinds of things.
Cons:
- The file output could be a PITA and frankly took more work to figure out than I wanted to deal with.
- They only really support Dropbox sync, which I’ve had poor luck with, frankly. So transitioning between my Mac and this iPad that my brother very generously gave me is kind of not the best.
- Costs money.
- Still has some of the formatting things like MS Word, which can be distracting at times.
Why I Stopped Using this Tool:
The syncing issues and the (non-)portability issue are the biggest problems for me, and as I try more and more to become app-agnostic (i.e., be able to write in whatever app is handy, whenever I’m able), Scrivener’s lock-in is more and more of a PITA. Not only can you not really share Scrivener files with people who don’t have it, but given that I was spending about as much time re-formatting everything in the end anyway, well… it was time to look for a better solution.
The New: Asciidoc, Git, Working Copy, Asciidoctor, Build Scrips
My first thought when I started really running into issues with Scrivener was to try and write a web app that basically did more or less the same things as Scrivener did, but used Git as a backend and gave one more control over the output. I mean, at the time it was still pretty recent that I’d finished VerseFinder, and I was doing more and more JS stuff as a part of my computational lit endeavors.
Then again, who has time to learn node.js? Not me right now, anyway.
So I put my “bart[leby]” app idea in an “ideas” folder and continued using the tools above in various combinations to suit the project: Scrivener for the thesis stuff (lots of files that I moved around a lot), iA Writer for the shorter pieces, and Atom (my Brackets replacement) when I was at work and wanting to look like I was in a code editor. The ideal solution would have been some plain text thing that worked in everything, which I sort of had in Markdown, but Markdown had some limitations that I struggled to get around (mostly requiring iA Writer to create Word docs. And yes, I know I could have used Pandoc (see below), but I wasn’t there yet).
Right. So.
Writing in Asciidoc
I started looking at asciidoc as a part of some general research for future jobs, and thought, “Hey, why not give that a try?” I was literally just looking for some new skill to add to the ‘ol skill-belt, and thought Markdown is very good for a lot of things (esp. when you need to wrangle developers into helping to write docs), it also is less good for other things. Asciidoc seemed a lot like DITA, a rather draconian but powerful tool I used at my first tech writing gig, and that was cool.
So I thought I might try spinning up some docs in Asciidoc to see what it was all about. I was starting a new revision of the thesis anyway, so why not?
Asciidoc lets you do a lot of useful things, like have a “main” file that pulls in all the smaller files. I like working in smaller files because of focus and eating an elephant one mouthful at a time. For example, a main.adoc file for one of my projects looks like this:
= Teller
include::1-opening.adoc[]
include::2-theater.adoc[]
include::3-walking-to-myras.adoc[]
// a note to myself
include::4-myras-i.adoc[]
include::5-intermission-power-out.adoc[]
include::john-overheard.adoc[]
include::basement.adoc[]
include::intermission-planned.adoc[]
// here I have some inline comments about some things.
Here is some text that gets included with the compile!
include::ending.adoc[]
////
== Notes
[various notes... which are private]
////
It’s a bummer there is no syntax highlighting (with Rouge, the built-in Jekyll tool, yet), but you get the picture.
An actual file might look like this:
= My Great Story
Daniel Elfanbaum
v.1.2 2020-01-15
Once upon a time there was a boy who said, "I like birds,
cats, bikes, and dogs." He lived a happy life, until
one day...
So anyway, I have my new bff markup language. It meets many of my requirements, being a plain text-based format:
- Very portable, and I can open it in pretty whatever I want to. Atom, iA Writer, Pretext, an app that I sometimes even prefer to iA Writer on the iPad, etc.
- Because it’s plain text it can be diff’d in Git. Oh, and also versioned, obviously.
- I can keep my files small, and I got to learn some new things.
Why Asciidoc instead of Markdown?
This is a great question. Aside from novelty (which ought never be discounted), Asciidoc has some toolsets, specifically Asciidoctor, that make it easy to compile to a bunch of different formats, especially once you get Pandoc in there (more on this below – and yes, I know that the Asciidoctor people recommend a different PDF converter, even in addition to their in-house one, which actually looks pretty cool and is something I intend to look into). Markdown typically requires some other processor, too, but unlike Asciidoc, there are about a bajillion markdown specs (or so it sometimes feels like), whereas Asciidoc has basically plain-Jane Asciidoc and I think maybe Asciidoctor extends it a little bit. But basically aside from novelty, Asciidoc is more convenient from a “build” standpoint right now, and so that’s what I’ve gone with.
Versioning with Git
Now, versioning, i.e., git. If you don’t know git that’s almost definitely because you’re not a programmer and that’s GREAT because git takes a bit of getting-up-to speed. That said, in addition to having to get familiar with it again for my current job, it’s a good skill for me, as a technical writer, to have. So forcing myself to use it? Great idea.
Beyond that, however, as I was starting to look into all of this, that, and the other, I was using a combination of iA Writer and the Pretext app along with Atom on my mac and using the iCloud Files thingy to store all of it, and I lost some fucking work. Maybe not a huge deal; I think I only lost about three pages, most of which were really revision pages (so the OG text was still there), but it kinda sucked, you know?
Git gets around this issue, and so even if it’s maybe (read: definitely) overkill for what I’m doing with it, it’s great for now.
To swap things between the mac and the various i-devices, all I have to do is use WorkingCopy, a handy little app, and I can pull, commit, and push just like on a computer! It does whatever magic it needs to to expose its filesystem to iA Writer, Pretext, and pretty much whatever else,
Building with Asciidoctor, Pandoc, and a Shell Script
Now, I can write and version my stories, blog posts, docs, whatever, and keep them tidy and safe in .adoc files, but how to, you know, turn them into Word docs so I can send them to journals so they can reject my stories? (I’m not bitter, I swear.)
That’s where Asciidoctor comes in, and that’s also where Robin Moffatt inadvertently hooked me up.
All it takes is a simple command in the command line, and BOOM! you’ve got a docx file:
asciidoctor --backend docbook5 --out-file - $INPUT|pandoc
--from docbook --to docx --output $FILE_NAME.docx
But what’s the fun in running the same command over and over, or else having to change the parameters all the time? None, that’s the fun. No fun. So I scripted it, and now I have a nice little questionnaire every time I want to build something:
====================================================
Welcome to the build script!
====================================================
What do you want to build?
1) Thesis Part 1
2) Thesis Part 2
3) Thesis Part 1 AND Thesis Part 2
4) Another Story
5) Working copy (whatever you've put into the build script)
====================================================
Enter your selection, good sir: _
Kinda neat, right? If you want I can send you the script to look at, but since I am a very novice script writer it is ugly and probably has a lot of errors.
But tl;dr every time I run this, it compiles the separate files into a single doc, and spits out a docx and a compiled .adoc file (just in case I want to read through the whole thing without firing up Word), and that’s about it!
Kind of neat, right? And way too complicated, I know.
Some Remaining Limitations
The biggest limitation, aside from how silly this all is setup-wise (which is really more a limitation for anybody else wanting to do this, no longer for me, given the sunk (time) costs), is that I can’t run the build script if I’m on an iDevice, only when I’ve got access to my computer. Is this a huge problem? No, not really. If I really have some kind of a deadline (HA: deadlines…), I’ll know that and just bring my laptop if I’m going to be working wherever.
That said: were this to become a requirement, I could probably figure out some automation scheme like I did for this blogshite. And actually I think I have an idea how I would do it.
So I don’t forget: create a new hidden dir on my website and have the output rsynced to that dir so I could download the file from any computer, assuming I remember my fucking password.
Edit (22 Jan 20)
Totally made that happen. Good to go.
I’m sure there are other limitations too, but that’s the big one I can think of now.
Conclusion: So What?
I spent a lot of time over the last week getting this all set up, and I’m proud of it, and so I wanted to write about it. That’s so what.
Beyond that, however, now that I’ve got this relatively convoluted setup in place for a “back end,” I have a relatively decent launching-pad for the “bart” project idea I alluded to earlier. Now all I need it an ass-ton of time to learn a bunch more shit, and then write the app.
In the mean time, I have a flexible writing workflow that makes me happy and that at least so far has improved my productivity as I find new little tricks here and there with Asciidoc and the whole includes:: thing (basically: I am able to write all over the fucking place and then arrange and rearrange the pieces appropriately as needed quickly).
And with that, I should probably get back to work. Why I thought it would be a good idea to do a ground up rewrite of my MFA thesis I do not know.
Various Post Scripts
The title of this post may as well have been, “Complicating the Writing Process to Make it Simpler, or Maybe I’m Just Crazy,” but I figured I’d try my hand at some organic search SEO what with all the toolset mentions. Ha-ha. You and I both know this will be read by you and maybe 5 other people.
If other people do end up reading this, this is mostly for my own pleasure, but also for technically-minded writers, technical writers, and other people who like to write but also play with computers.
Also, do you like the new Dark theme? I basically just stole the coloring from Atom.