Not long after I started working professionally as a Technical Writer, I decided to design a content strategy that would eliminate Microsoft Word from my personal writing. What I’ve got now works fairly well. It’s much more streamlined than my previous setup using Word, but there are several areas where I’d like to improve.

Why not Word?

Microsoft as a whole manages to cling to this status as a suite of indispensable tools despite being entirely outclassed by other (free) products. I could point out many more problems I have with Word, but I’ll restrain myself to only those related to the topic of this post—Submissions.

Word doesn’t modularize

Meaning you can’t easily break the things you write into smaller pieces to reuse in multiple places. Your submissions likely contain several identical pieces of content:

  • Your contact info
  • The date
  • A short bio

Maybe a few others. If you’re typing them out each time, you introduce the possibility of typos, inconsistencies, errors, or oversights. Even copy & pasting those items from a master document is an unnecessary use of time, and could result in unintended styling if you forget to correct it when Word pastes the wrong font or indentation into your document.

Word does have Quick Parts & Auto Text that can reuse chunks of content, but they’re unsurprisingly difficult to store & edit. And worst of all, they only work on your local installation of Word; the reusable content you create isn’t available globally.

That last part is probably only a concern for professional writers who need to share repositories with other authors, or people using virtual machines. If you’re gonna continue using Word, look into Quick Parts & Auto Text to make you writing life a bit easier.

No distinction between presentation & semantics

Word uses a proprietary markup (just a custom XML, I think) to code the content you add to a document. If you’ve ever copied something from Word and pasted it into a different program, you’ve probably seen the jumbled markup that Word applies.

This is a problem when you need to copy & paste poems into a submission document. Word has a feature called Styles that creates semi-separation between your content & how it appears. But even using Styles and copying a poem from one Word document to another, your formatting is rarely preserved.

Version control is a nightmare

Briefly, version control is a method of tracking & managing changes to source files. “Source files” could be:

  • files that build a website (like HTML, CSS, & Javascript).
  • files that create an app (Java, Rust, etc.).
  • any other document (Word, PDF, etc.).

A version control system (VCS) tracks every modification to the source files, and allows you to access any earlier version of those files. The industry standard VCS is Git. It can get extremely complicated, but if you set up & utilize a Git repo, you can feel confident that you’ll never lose anything you commit to the repo.

But you can’t really track Microsoft documents (Word, Excel, etc.) with Git because of their proprietary markup. Git will save those files, but you can’t see the character-by-character changes you can with plaintext files. Which means if you wanted to find a previous version of a poem, you wouldn’t be able to tell which version you wanted with Git. If you don’t use a VCS, you probably have a dozen files for each poem, with _v# appended to the filename, and you still have to open each one to find the historical version you’re looking for.

Dropbox has a version control feature, but it’s premium. Google Drive includes versioning for free! Though I’m not sure how well it works or how easy it is to use.

It’s possible to set up a workable version control scenario with Word, but you need:

  • to be the only author (probably true).
  • access to Sharepoint (it’s not free).

There’s a better (open source) tool for that

Whatever you want to do with Word, there’s an easier, more efficient tool that’s probably free. In terms of submitting your poems, there’s no need to pay for Word when Google Docs & LibreOffice can save as .docx.

Editors, I am simply begging you to accept submissions in at least one format that is not Microsoft Word.

Submission architecture

I don’t know much at all about web development, just enough to make my website run, which I learned in order to make it run.

In the case of my current submission architecture (which I’ll refer to as my “localhost setup”), I used this guide by John Foderaro to get started. I doubt I would’ve figured it out on my own, or even had the patience to try. (Although I think I had to play around with some of the configurations, and I definitely used TextEdit—nano is atrocious to work in.)

Below is a detailed look at how I use HTML, CSS, PHP, & Apache to store poems and create journal submissions.

HTML is the markup language that the web is written in; it defines the structure of your website & pages.

CSS defines what your HTML looks like.

PHP is a server-side scripting language; meaning, your server interprets the code.
(Javascript is a client-side scripting language, so your browser processes the code, just like it processes HTML & CSS when you navigate to a website.)

Apache is an open-source server. At the most basic level, a server accepts requests from a client (your browser) and responds with the content it's storing (a website).
Apache is built in to Macs, so I just had to turn it on using the guide I mentioned above.

Poems

I use a very simple file that I titled poemTemplate.html to write & save each poem. It’s not, strictly speaking, a template because I have to command + shift + S to save; it’s possible I could create templates in my editor (Atom), but I haven’t taken the time to look in to it.

I save each poem at /Users/<username>/Sites/poems (on Mac), which you can access in Finder when you want to edit a file, or view in your browser by navigating to localhost/~username/poems (where poems is a directory you add after setup). You want to use your browser to view because that forces the server & browser to run all your code (like CSS, PHP, Javascript, etc.).

<!DOCTYPE html>

<head>
  <title>Title</title>

  <meta name="viewport" content="width=device-width, initial-scale=1.0">

  <link href="../poemStyle.css" type="text/css" rel="stylesheet">
  <link href="../fonts/KohinoorBangla.ttc" rel="stylesheet">
  <link href="https://fonts.googleapis.com/css?family=Montserrat" rel="stylesheet">
</head>

<body>
  <h3>Title</h3>

  <p class="epigraph">Epigraph</p>

  <p>Body</p>

  <p class="dedication">Dedication</p>
</body>

Here’s what happening in that file:

!DOCTYPE Tells the browser what version of HTML the file uses.

For HTML, the current version of HTML, it's the very simple !DOCTYPE html you see above. It was more complicated for older versions.
head & metadata elements Contains metadata elements—elements about the document:

title
The name of the document, which appears in the brower's title bar or page tab.

meta name="viewport" …
Tells the browser how to control the page's dimensions. Essentially, it sets the width of the page to the screen-width of the device displaying it, so you can view on desktops, laptops, tablets, & phones.

link
Creates a relationship between the current document and an external one. In this case, I'm linking to my stylesheet so my CSS is applied to the poem, and to some fonts I like. "KohinoorBangla" is a font on my computer; the other is one Google makes available for free at that URL.

There are many other elements that could appear here.
body & text elements Contains everything that actually gets rendered in a browser.

The header & paragraph tags are pretty straight-forward. Two p elements include classes; those classes are defined in my stylesheet to look a certain way (dedications are indented & italic; epigraphs are right-aligned & italic).

Depending on how I want a poem to look, it can get fairly complicated to tag it and apply the correct CSS. I won’t get into specifics here, but I’ll say that in my experience, it’s less complicated to get HTML & CSS to do what you want than MS Word. Plus, if you supply someone with your HTML poem & stylesheet, they’ll see exactly what you intended, which you can’t always say for Word, even when you’re both using the same version of Word.

Submission documents

Of course, no journal I’ve ever seen accepts submissions of HTML documents. So my final output is always to PDF.

This file is submissionTemplate.php:

<head>
  <title>JOURNAL poetry submission</title>

  <meta charset="utf-8">
  <meta name="author" content="Andrew P. Dillon">

  <link href="../../poemStyle.css" type="text/css" rel="stylesheet">
  <link href="../../fonts/Kohinoor" rel="stylesheet">
  <link href="https://fonts.googleapis.com/css?family=Montserrat" rel="stylesheet">
</head>

<body>
  <!-- CONTACT -->
  <?php include("../../contactInfo.html"); ?>

  <!-- JOURNAL -->
  <p id="journal">JOURNAL poetry submission<br />
  <?php date_default_timezone_set('America/Chicago'); ?>
  <?php print date("d M Y", time()); ?>
  </p>

  <!-- TOC -->
  <h4>Contents</h4>
  <p>
    <ul>
      <li><a href="#coverLetter">Cover letter</a></li>
      <li><a href="#poem1">Poem1</a></li>
      <li><a href="#poem2">Poem2</a></li>
      <li><a href="#poem3">Poem3</a></li>
      <li><a href="#poem4">Poem4</a></li>
      <li><a href="#poem5">Poem5</a></li>
      <li><a href="#bio">Author bio</a></li>
    </ul>
  </p>

  <!-- COVER LETTER -->
  <div class="page-break" id="coverLetter">
  	<?php include("../../coverLetter.html"); ?>
  </div>

  <!-- POEMS -->
  <div class="page-break" id="poem1">
  	<?php include("../../poems/.html"); ?>
  </div>

  <div class="page-break" id="poem2">
  	<?php include("../../poems/.html"); ?>
  </div>

  <div class="page-break" id="poem3">
  	<?php include("../../poems/.html"); ?>
  </div>

  <div class="page-break" id="poem4">
  	<?php include("../../poems/.html"); ?>
  </div>

  <div class="page-break" id="poem5">
  	<?php include("../../poems/.html"); ?>
  </div>

  <!-- BIO -->
  <div class="page-break" id="bio">
  	<?php include("../../shortBio.html"); ?>
  </div>
</body>

It needs to be a .php file so the server will parse the PHP commands (the date declaration & includes). Includes, btw, are exactly what they sound like—they navigate to the file I specify and insert everything in that file into my submission document. That way, I only have to maintain:

  • one file for contact info.
  • one of each poem.
  • one short bio.

In my profession, we call this “single-sourcing”.

I'm not including the CSS here because that file is lengthy & unwieldy, and I don't want to try to explain the use cases for each class.

Workflow

To bring it all together, here are the steps I take to create a submission document:

  1. Open the template and enter submission info:
    1. In the head element & JOURNAL section, replace the JOURNAL placeholder with the name of the journal I’m submitting to.
    2. In the TOC section, copy & paste the titles of each poem.
    3. Probably delete the COVER LETTER section because cover letters are unnecessary.
      (More on this in a future post.)
    4. In the POEM section, enter the filename of each poem in front of .html.
    5. Type command + shift + S to Save As.

  2. Create a PDF:
    1. In my browser, navigate to the folder where I save my submissions: localhost/~username/submissions.
    2. Open the file I just created.
    3. Right click and select Print page.
      Make sure to right click on some negative space (not on any text), or else you’ll create a file with only what’s highlighted.
    4. In the Print dialog, select Save as PDF, and choose a location to save.
      The specifics here depend on which browser you’re using. Safari seems to work best. Chrome works too. Brave does not.

  3. Open the newly-created PDF and add page numbers.
    This is an Adobe premium feature now, but I have an old version of Acrobat Pro. I haven’t found a way to create page numbers with markup alone; although paged.js seems promising.

Here’s the cover page of the PDF I end up submitting:

A screenshot of an example PDF generated by my localhost submission workflow. It contains author contact info, the name of the journal I'm submitting to, the date, and a hyperlinked list of the poems it contains.
A very simple submission document

Unfortunately, some journals that I really want to submit to still only accept .docx files, so I do occasionally use Word. If you’re a student or work for a big enough company, you can usually get a discount on MS Office. At my previous employer, I think I upgraded to my current version for like $10. Of course, Office365 is a web subscription model now. I had to edit OneNote in the browser a couple times, and it’s essentially unusable. I can’t imagine a browser-based Word editor isn’t flaming garbage.

Room for improvement

You can probably see that a lot of the process is still somewhat manual & tedious. And considering I’m writing a book using a static site generator, which has its own repository of poems, I am still duplicating effort in a major way. Here are some ways I’d like to streamline:

True single-sourcing with submodules

The biggest problem I have is maintaining multiple copies of each poem. Right now I have three poetry directories:

  • The localhost setup I detailed in this post
  • The custom Jekyll project for my manuscript, The Great Permission (which only includes the poems that are actually in the book)
  • A default Jekyll project called poetry (which I don’t keep updated, but is meant to replace the localhost setup when I finally implement submodules)

Plus, I have this Jekyll project, the one that hosts this blog. Obviously, it doesn’t currently include any poems, but I’d like to one day add a Read page that compiles poems that were published a while ago or aren’t available online.

Michael Currin, who seems to be the most active contributor on Jekyll Talk, pointed me to one of his projects that explain submodules & how to implement them. I just haven’t taken the time to research the topic in-depth. I have read his About page, which includes this advice:

I would avoid trying to make commits of new content in [the submodule] directly. Rather make them in the external repo in a different part of your machine or on GitHub, then update your submodule and commit the new reference.

Wait, so… once I create the relationship between an external repo & a submodule, I can’t update the submodule? I feel like I must be misinterpreting that. I need the submodule to contain all my poems, and be contained within two external repos (my manuscript project & this project). And as I edit, I’ll need to make new commits to the submodule of poems. So if that complicates the situation to enough of a degree, I may have to find another solution.

A "commit" is Git's terminology for content you save to your repo.

“Well,” you may be saying, “if Git is such a pain in the ass, [reader, it truly is] then why not try some other VCS?” Fair question. Git is one problem, and I have another:

Git is a necessary evil

Github Pages requires Git. Jekyll was created my Github’s cofounder, and has free, built-in support for GitHub Pages, which hosts my site. Right now, I just pay for the domains to this site & my book. If I didn’t want to use Git, I’d have to find another host.

To be fair, Git is probably the best VCS out there. It’s just insanely complicated because it’s solving insanely complicated problems. Ideally, you wouldn’t have to be aware of your VCS—it would just work, the way Dropbox works without you thinking much about it beyond the initial setup. But Git forces you to interact with it in order for it to do anything; and its commands are complicated & unintuitive.

Jekyll is “feature-complete”(?)

That is, its future is uncertain, and the project may no longer be under active development. The primary contributor died suddenly, and there’s been a lot of speculation about who, if anyone, will maintain the project. Reading some other articles about this, maybe the concern has been overblown. But if there are no devs, then it’s only a matter of time before Jekyll won’t be safe to use. It’s a Ruby gem, and needs to be updated to support recent Ruby releases for security.

Right now, I’m not going to worry about this. I’ve invested too much time & effort into Jekyll & this toolchain to make a huge change now.

Page-level variables

Looking at the localhost setup in isolation, the only real issue is that I still have to copy & paste a decent amount. In contrast, with a Jekyll project, Liquid allows me to access variables on the pages I’m targeting so they’re auto-filled in each document.

For example, here’s what my submission template could look like in the poetry project:

---
author: "Andrew P. Dillon"
title: "JOURNAL poetry submission"
date: 2021-12-01
dateModified: 2021-12-01
layout: submission
categories: template
tags:
poem1: apologiaNoAnswers
poem2: todayYouWillDie
poem3: forgingTheBoy
---
{% assign poem1 = site.poems | where: "permalink", "{{poem1}}" %}
{% assign poem2 = site.poems | where: "permalink", "{{poem2}}" %}
{% assign poem3 = site.poems | where: "permalink", "{{poem3}}" %}

<body>
  <!-- CONTACT -->
  {% include contactInfo.md %}

  <!-- JOURNAL -->
  <p id="journal">{{ page.title }}<br />
  {{ "now" | date: "%d %b %Y" }}</p>

  <!-- TOC -->
  <h4>Contents</h4>
  <ul>
    <li><a href="#coverLetter">Cover Letter</a><br /></li>
    <li><a href="#poem1">{{poem1.title}}</a><br /></li>
    <li><a href="#poem2">{{poem2.title}}</a><br /></li>
    <li><a href="#poem3">{{poem3.title}}</a><br /></li>
    <li><a href="#bio">Bio</a></li>
  </ul>

  <!-- COVER LETTER -->
  <div class="page-break" id="coverLetter">
    {% include coverLetter.md %}
  </div>

  <!-- POEMS -->
  <div class="page-break" id="poem1">
    {% for poem in poem1 %}
      {{ poem.content }}
    {% endfor %}
  </div>

  <div class="page-break" id="poem2">
    {% for poem in poem2 %}
      {{ poem.content }}
    {% endfor %}
  </div>

  <div class="page-break" id="poem3">
    {% for poem in poem3 %}
      {{ poem.content }}
    {% endfor %}
  </div>

  <!-- BIO -->
  <div class="page-break" id="bio">
    {% include shortBio.md %}
  </div>
</body>

The variables streamline everything. In this case, all I need to do is:

  1. Open the template and fill out the YAML frontmatter (the top of the document, between the ---).
  2. On the command line, navigate to the project and serve the site: bundle exec jekyll serve.
  3. Navigate to the submission in my browser (it also gets a localhost address), and save a PDF as described above.

I could also set some of those YAML variables as default values (like author & layout) in the config file, so I wouldn’t have to include them in each file. And there are ways to automate creating PDFs, but all I know of, like PrinceXML, are paid. Pandoc might be able to handle it, but it seems very complicated. Jekyll might be able to do some post-processing using hooks, but again, I haven’t looked into it yet.

Final thoughts

Setting all this up is pretty complicated—especially the Jekyll projects, and especially if you’re not familiar with any markup or scripting languages. It’s a big effort, both in terms of time & mental energy. But then again, so is writing poetry & submitting

The good news is, like many open source projects, there’s a large community of people who have documented common use cases & issues and who are willing to help. You also end up saving a lot of time & energy in the long-run when you leave behind proprietary software.

Feel free to drop me a line if you’re a poet who needs a push in the open source direction!