Lou: Hi, this is episode 57 of Write While True.
Write While True is an infinite loop, and that’s because we think of writing as an infinite game, a game we’re playing for fun and to get better at, like a game of catch. So in each episode, we’ll tell you something we learned about writing, and then we’ll throw you the ball with a writing challenge or a prompt.
I’m Lou Franco.
Brian: And I’m Brian Hall.
And today, once again, we’re talking about tools, but this time focus on tools for publishing and collaboration in writing, which is all a bit more complicated than what text editor do you use?
So, to start at the simpler end of the spectrum, though, there’s blogging and then there’s publishing things like books and pamphlets and whatnot. So let’s talk first about blogging tools, publishing to the internet.
This is something that still mostly can be done without bringing in other humans. At least I think we both do it in a way that’s self-serve, under our control.
So, briefly, what I’ve used in the past was Jekyll. It’s a static blog generator written in Ruby. I don’t use Ruby or know Ruby, but Jekyll is kind of a standalone tool.
It’s really nice. You write markdown files. You run a command. It generates the blog. It integrates with GitHub pages. Good stuff.
I used it for quite a while and then decided that I needed to build my own in Clojure as a project to help me learn Clojure. And that is in progress.
So, I’m getting there.
But that’s my current stack is almost no stack or a non-functional stack that I’m building as I go. And all I’m going to say is I’m enjoying it and I think it’s fine. I’m still writing markdown files. So, they’re still portable and I can do anything with them.
And any day now, I’ll be able to type a Clojure command and spit out a blog. It’s almost happening.
Lou: Nice.
Brian: And then, actually, I’m really enjoying the old school feel of just dragging the converted HTML files over to a CDN via FTP client. And that’s how it gets published.
So, for me, that’s the stack right now. I’m sure I’ll get fancier with it at some point. But right now, I don’t mind the friction. I don’t mind that there’s a manual step. I don’t publish all that often. So, that’s me.
Lou, I believe you’re a bit more logical, frictionless, robust. Tell us about your process.
Lou: I have two blogs. One is loufranco.com. And that’s on WordPress. It has migrated over time. It’s been around since 2002 or something like that. Maybe a little later. I don’t remember. Early 2000s.
And it was originally on CityDesk. That’s the Fog Creek software. It doesn’t exist anymore. It’s desktop. It was static site generator, desktop app.
Then, I converted it to RapidWeaver, which is another static site generator, desktop app for Mac. That still does exist, but I migrated off that to WordPress. It’s been WordPress for a long time. I’ve been writing posts on it for more than 20 years. We’re getting close to 800 posts because I have spurts where I do more or less.
And that goes relatively well. I just type in a WordPress. New post page. Hit publish. And it’s very easy. Hardly any friction at all. And therefore, I do it.
The other blog I have, I made myself in Django around 2013, let’s say. And I have to keep updating the Python, updating the Django. And it probably has on the order of a couple of dozen posts. Now, that site is appomat.com, and it’s only about iOS app development. And it’s more about tutorials. And I haven’t written on it in a while.
I don’t even remember the last time. And my last act with it was to convert it.
My hosting company decided to charge a lot for Django hosting. So I decided to turn the whole Django thing into a static site generator. So instead of live running a Django web app, my Django site generates all the pages. And then I do what you’re doing, FTP them over. And since the day I did that, I haven’t posted one more post.
So it exists only because it does get traffic and it does have useful information. They’re all like iOS tutorials that still matter. And I did a lot of Apple Watch tutorials that still apply.
So I decided to leave it up.
But as soon as I made the decision to make it a static site generator Django thing, it just got too complicated to post. It’s too complicated to post. I don’t even think I know how. I’d have to refigure it out.
Brian: So there’s definitely a lesson in here, I suppose. And a lesson for soon-to-be future me about the complexity of the pipeline to go from I typed the thing to the thing is live.
WordPress is great for that. Open up the editor, type, press a button, and you’re good.
At the moment, because I’m building my own tool, it feels like a celebration to drag the file in the FTP client over to the CDN. But that won’t last forever, and I will have to make that easier, or we’ll probably end up where you are with Apple Magic, where I don’t want to bother.
Let’s talk more about pipelines and processes and different tools in the context of collaboration and more ambitious publishing projects, like, say, a book. Because this is where it gets really messy, and the friction gets really intense.
And I don’t know if I fully have an answer, but let’s talk about what we’ve done, where we’ve struggled on this account.
And let me go first. As far as writing and publishing a book and working with editors and proofreaders, the publishing world is fairly old school and fairly cemented in their ways when it comes to Microsoft Word is everything.
To most editors, developmental editors, copy editors, they want a Word doc, and they’ll give you back a Word doc. And, man, I hate that so much, and it is also a part of the universe I can’t really change. And then proofreaders, for the most part, expect a PDF, and they’ll send you back a PDF. And you can find folks who will work outside that realm, but that’s been my experience.
And so the sad, sad news is no matter what amazing obsidian system you have or static file you wrote your masterpiece in, at some point you’ll have to turn it into some other format to hand it to some other human who will do very valuable work. But now you’re in Microsoft, or best case, maybe now you’re in a Google Doc.
Then from there, to actually publish it, say on Amazon KDP, you need to generate a formatted, laid-out PDF, like a pixel-perfect representation of the interior layout. So, again, you’re going to lose sight of your beautiful plain text at some point. And that is the struggle, that is the process, especially when you’ve moved downstream, you’ve gotten some feedback on, say, a PDF with markup around typos.
Where do you go back and reincorporate those changes? Do you now have to edit in Microsoft Word? Are you able to take it back to the original text file? So, my aspirational state is to have a workflow that goes from the plain text into the docx file for the copy editor, but then when I get that back, I’ll go and make the edits in plain text, and I can re-export that to PDF for the proofreader.
They will catch mistakes, but then I’ll go edit those back in the plain text. And then the final step is interior layout, and that is visual, so you can’t do it in plain text. And for that, I’ve used a couple tools.
One is called Vellum. It’s a Mac-only desktop app. It’s pretty good. It’s meant more for fiction writers, and it kind of shows, but it works. And then at Useful Books, we’re working on an internal tool for interior layout that uses a JavaScript library called Paged.js, and it is kind of the dream to have you write CSS and JavaScript to define the book’s interior layout.
This means that everything from the manuscript and markdown to the styling and presentation can all be under version control in Git. We’re not fully, fully there yet, but this is very much a work in progress because the pain of moving from platform and format to platform and format and back and forth between people is so intense. I just personally hate it so much.
Lou: And then will help this book also accept that format, or whatever I write, sorry, whatever I’m writing, the plain text, will that also go in to help this book as well?
Brian: Yeah, yeah.
And so that’s another collaboration step is beta reading that comes before all the painful stuff I’ve been talking about with proofreading and stuff. And yeah, so help this book. You can upload markdown or a zip file with your markdown files and your images, whatever you’ve got. And you can import a markdown manuscript and help this book.
And so you can keep it, again, keep it as long as you can in plain text and make your edits in plain text. And then as a final step, last resort, or as a bit, maybe like a detour that reverts back to plain text, send it to editors, proofreaders for input. So that’s the dream. It’s not fully realized.
To motivate why that matters, why anyone should care, Lou, I’d love if you would share a bit about some of your experience with working with collaborators for your book. All the many formats and email attachments and stuff. How did that go?
Lou: Yeah, so I should say I’ve talked about Help This Book many times in this podcast, beta reading. I’ve talked about how I used it to get early feedback. And I just want to say Brian does work on Help This Book. And that’s how we met. And that’s why I’m asking him questions about the features of it since I still do use it. Um, and, but I’ve, I’ve talked about it extensively, how I use it.
I tended, so I’m going to just say generally, all of the tools that are not my drafting tools, all seem to have a problem with not fully implementing all of the features that I would need. In order to get my book to be high fidelity across into their world, except for Word.
So like, so Word does, Word has like every feature there has ever been.
Brian: I hate it, but you’re right. Way more than I could ever need.
Lou: So Word can do it. So, but everything else, including like, I’m going to just say, I took a quick look at Vellum and it couldn’t do tables or something. And then I was like, I don’t know, maybe you can, it’s like, I couldn’t figure out how to do it. And then it’s like, I kind of gave up on it immediately because it couldn’t really, and tables are kind of important in nonfiction, let’s say programming books. Like, like I write, they probably will have tables in it.
I ended up reducing the number of tables I use to the minimum, um, thinking sometimes like, okay, that doesn’t need to be a table that could be a bullet list. And I would do that just to, because, because of these, these tools weren’t, weren’t doing a good job of, of taking tables.
And that’s been true in almost everything I’ve tried to bring my draft into. There was something that they, that they didn’t do right. And the big things are images, tables, footnotes, internal linking. These are all the things that you’re going to kind of probably struggle with when you try to bring it across to anything.
So I would, I would love for that to be more high fidelity. Um, but that’s, that’s where kind of, I’m coming from. In the editing step, my editors all used word and I didn’t want to fight with that. And so I decided to, um, use tools.
I think I used pan doc to convert my, uh, well, I was using Scrivener at some point and Scrivener probably made a good enough word document. And then once I did that, once I decided I had finished the first draft and now I was in word for my first developed developmental edit or my first big edit. I just stayed in word from then on and it was, um, just a series of word documents back.
It was very painful, but like there’s nothing online anymore. Nothing, nothing I could version control anymore. A word document went to my editor, a word document came back with edits and comments.
I did a revision in that same word document, gave it back, did another round. And gave that same word, you know, a copy of that word document to my proofreader, got it back. Um, and then that went to, so then I also hired a formatter to turn it into this pixel perfect PDF.
They accepted word document. I gave them that same word document and now they were giving me back, uh, um, Mobi or EPUB and PDF for print. And we had to stay in that. So any, anything I wanted to do, I had to explain how to do it in that. And then do it back and forth.
I gave that final thing to a final check proofreader, like literally just like look for anomaly, like anomalies in the publishing process. So don’t, don’t try to do grammar checks or anything like that. Like, like just if you find one, I don’t care anymore, but, um, we’re looking more for like a footnote. That’s not in the right place, or it doesn’t go to the right place or an internal link. That’s not right. Or a table that’s janky, you know, like because of the publishing process.
And so I just gave them the EPUB. They use Kindle. The, the, there’s a, there’s a tool that Kindle will give you to where you can read, um, EPUBs you get locally. Uh, it’s like preview tool or whatever, Kindle previewer. And, uh, and the PDF, uh, that, that for the ebook.
Yeah.
So once I crossed the line into tools that my collaborators use, I just stayed there for the rest of the time. Cause there wasn’t a lot of writing happening, just revising. And it was just easier to like, not, if I did try to do round trip conversions, I am sure I would have lost things I cared about.
So I decided not to do that. I went forward only through, through word into ebook and, and, and PDF.
Brian: Yeah. There’s no great answer.
Once you’ve moved into word, I think the options are you stay in word and there are benefits to that because you’ll get back suggestions, track changes from your editor and you can just click accept, accept, accept.
And that’s really nice.
If you want to instead go back to your plain text manuscript, you have to manually go make all of those changes with two documents side by side on your screen. That’s kind of a pain.
Either way though, either way, you’re, you’re kind of stuck in word or you’re stuck with more manual interventions and the chance that you mess up in doing so.
No great answer here.
And I think that’s, I guess maybe we’re angling towards a takeaway, a tough love takeaway for this episode. Which would be, except that as you bring in collaborators, you will need to change formats or tools or both. And just know that that’s a part of the process. I would argue for.
Lou: Think, you know, plan for it maybe a little bit.
If, uh, I would almost try to, to do those conversion as tests early on. So taking on, taking on some of the, you know, things that we do in programming, like where we do iterations, like maybe make a little document that has foot, all the things that you might have footnotes, internal links, tables, images, and go see how that works.
With your things that you’re going to be going into and kind of get the idea of what you might need to do or not do. And maybe if you can talk to the developers who are, you know, making those tools, like get them to do, you know, show them small examples of things that they could do to improve your, your process.
I, um, yeah, in some parts of my process, I had to turn tables into images. Like I had to take snapshots of tables, turn them into images so that the tape, and then put that in as the table. It wasn’t ideal, um, but for, I was just, I was just trying to get feedback, uh, in the system from using a, um, um, a public web systems that just didn’t handle tables. Like there’s nothing I could do about it, but I needed the table.
So, uh, it, yeah, but I think I would do that this time, like do a little test to see, and then maybe think about not using a feature of documents. Maybe, I don’t know, you have to think about that, like what, what serves the reader and what serves your, your system. But, um, if I, if I might, I might think about it, honestly, but, um, especially, I mean, I think the big ones tables, like, do I really need to, I probably need images and footnotes and cross-linking.
But the other, the other thing I’ve been sort of considering is using a tool that can handle more of this. Uh, I know that there are bookmaking markdown styles that, um, but I haven’t looked into them. So, but that might be, that might be another thing I would do.
Think about it.
Brian: It’s, it’s quite a rabbit hole, but it’s also really satisfying. Once you’ve bumped up against this, these limitations and had to compromise and not been able to include stuff in your book, if you’re still in the game, the, the temptation to go write your own or use lower level tools like libraries instead of apps, it’s, it’s real.
And it’s pretty satisfying. I think it’s worth it for a certain personality type.
And I’ll say too, actually, you can, if you’ve not written a book before and you know, you’re writing a book, you can take it all the way end to end as a test run early in the process. Once you’ve written a chapter or two, you can export those to PDF. You can use a layout tool to get them into book formatted PDF, which for example, there’s a wider margin on the inside of the page than the outside of the page because of the fold in the book.
It’s this kind of stuff. Like there are tools that handle that for you. You can go do that, export the PDF, go create your book in Amazon KDP, upload your PDF with a bunch of blank pages and order a proof of the book and get it back.
If you want to go that wild with it. And I think it’s actually not a bad idea because a week later you’ve got this little ugly mock-up cover and only one chapter of actual text, but you can hold it in your hands. And now you’ve seen all the steps and now you know when the interventions will come and what some of the limitations are. It’s pretty motivating.
Lou: I will say this, and this might be interesting.
When I wrote my first book, and this is back in 2012, 2013, I wrote it for Manning, the publisher Manning, and they had a mandated process for writing the book that was, I now can understand, put into place to streamline the whole process.
So what they did, they had two accepted ways. I decided to choose the way with Word. And basically what they did is you had to do one document per chapter. And with a mandated style, so they gave you like a style template, and you had to use their styles in the specific ways they wanted you to use them. So their header, their subheader, their everything, figure, everything was down to every kind of style. You had to style the text exactly using their built-in styles.
And then from then on, things were very easy.
And I didn’t have to do anything past the writing part and the collaboration on the editing, but it was super easy to get from the drafting through the process. And I don’t know what they had to do to actually make the books, the e-book, but I think it was easy because of the way they had done that system.
And so that’s another thing to consider.
Like just decide that you would like the entire end of the process to be very easy. And then I’m going to just say you’re probably going to have to use Word. I just think you’re going to have to. And then you could do this. You could mandate a style guide. I’m sure you could find one. And then one that can programmatically be turned into the next stages down the line.
But obviously Manning invested in their own publishing tools, which we don’t have access to. The other way that I did not decide to use was a more plain text way. But it seemed like the collaboration part was going to be complicated, so I decided not to do that because I wasn’t exactly sure how that was going to work. Because that part you can’t do in plain text very easily. And what I mean by that is commenting, revisions, things like that.
Brian: There’s a world where you sort that out on, say, GitHub or a similar platform. And you have commits, pull requests, pull request threads.
Lou: Getting a person whose ability is grammar, writing, storytelling, which is what you want from your editor. It’s not the ability to use GitHub. It might limit. I mean, it’s impossible. It’s not possible. But it might limit who you could get to help you.
If you’re writing a technical book and you have a good person who is a great writer who’s also a programmer, I mean, and we’re the community that could find that, then I definitely would consider it.
Brian: Let’s move into wrapping.
And I think we have a great segue here because we have talked about all of the complication and challenge and mess of collaboration as compared to the perfect little world where you’re writing plain text and publishing it by running a command line script or something on your local machine.
And when you bring in other people, it gets more complicated, but you get input and sometimes a level of quality, I guess, that just isn’t there for multiple minds.
And so this season of Write While True has been a collaboration as well. And it’s one that I’ve really enjoyed.
Lou, would you talk about what’s coming next?
Lou: So season five started with episode 48. And that was when Brian joined this podcast. And this is now the 10th episode, episode 57. And we have decided that this is now the end of season five.
And we’re going to take a little break. Not too long, but maybe a few weeks. And we’re as we plan for season six. And what we have decided is that season six will be about talking to other people.
So bringing in guests to talk with the both of us that are people like us in our community.
So people who are programmers or software developers, maybe primarily who are writing in public blogs, books, articles, whatever. And we want to talk to them about their writing process. So we will, of course, cover some of the topics that they might be writing about just to ground it and give context.
But mostly what we’re interested in is finding out how other people like us do the writing that they do.
We’ve explored that in 10 episodes between the two of us. And now we’d like to bring others in and talk to them. And those episodes might be a little longer. I think they might be. I think we’ll have a lot to talk about. It’ll be at least three of us on the call.
So I’m looking forward to it. How about you, Brian?
Brian: Yeah, absolutely.
A lot of the same topics that we’ve covered this season about who you’re writing for and how you sit down to write and the emotional turmoil of writing and publishing and receiving feedback.
All of that stuff will maybe even get into the dreaded territory of marketing for those who have written a book or are trying to grow an audience.
All of this stuff is on the table.
And, yeah, we’re into the technical topics, but really want to talk about the process itself. And I think there’s a lot there.
Lou: Yeah, and I think a lot of these people have come at it in a similar way that we’ve come at it because of our background.
And, you know, so, you know, some of the things we have talked about is like how to apply some software development processes to the idea of writing.
Not just like writing software, not by writing software, although we have talked about that.
But just the idea of iterations, the idea of the way we do collaboration, you know, for example, getting comments, RCs, things like that.
The idea of beta reading even comes from the idea of beta testing. And, you know, some of the people I’ve talked about in these podcasts, they were software developers who happened to write.
So that’s why the ideas have coalesced around those. So I think we’ll continue along that vein.
And so we look forward to to see you in a few weeks. Stay tuned and please, you know, keep us in your podcast software because it might be a few weeks, but we’ll be back with with season six and a guest and start talking about these things together.
And that was episode 57 of Write While True. It’s a podcast where we love infinite loops as long as they’re fun.