Working with a publisher means you don't get full control. In fact you get surprisingly little control and everyone behaves like they know better than you about everything. Which they probably do.
One thing you get no control over is the format you're going to write your book in. But hey, the publisher churns out a new book every week and they've been doing this for years. If somebody knows the best tools to write a book, it's going to be them.
Naturally they ask you to write in
.doc. Word gives you marvelous diffing features, there's comments, you can do styling and layouting, and it's perfect for having multiple people working on the same document simultaneously.
Wait ... no it isn't. In fact Word sucks at all of that!
My heart sank the moment I opened LibreOffice to start working on Data visualization with d3.js way back in January.
I can't use Word. Last I checked there still wasn't a linux version for my main computer and the pirated copy I have for my Mac crashes as soon as the software runs. Something about fonts.
LibreOffice isn't bad per se, but there are better writing tools out there.
Especially when it comes to code samples. Why am I dealing with code samples in .doc?
But that's what the publisher wants. They even have a fancy base template with all of their custom styles that tell the layouting team what to do. I imagine they export into a better format and work from there.
It's difficult to pinpoint why exactly working with this format has been so infuriating, but here are some issues I've run into:
Because of collaboration you have to turn on
record changes. This lets the editors see what you've been up to. But it's slow without
show changes. Suddenly you're working with paragraphs that look like this:
This makes it very easy to miss a space here and there or have too many full stops in a row.
There's also a bug in Linux LibreOffice - not experienced by anyone else online as far as I can tell - that inserts a blank line after every paragraph with an edited last character. The new line is inserted every time you open the document.
Which makes editors cross with you and question your sanity.
And sometimes, randomly, when you change the styling of some text the styling would vanish somewhere between you and the editor.
Oh and no matter what format you send the document in (I liked
.odt because it causes the least problems for LibreOffice) you will get it back as
A format LibreOffice's got catastrophic problems with.
Last week I was happily editing away, acting on the technical feedback I'd gotten, and after a few days I open the document ... it was 5 pages long. Not the 38 it was supposed to be. Five.
Everything just up and vanished.
But I'm using Dropbox so there's a backup every time I click Ctrl+S. I'm safe right?
The last working version was 37. Out of 131. I was pretty mad.
Some 15 pages of editing went poof.
It happened again a few days ago. But I was more careful and only lost 5 pages. Then I converted all current versions to
.odt. That seems to work.
The collaboration has been wonderful too!
Because we can't all work on the document at the same time, but have to resort to sending it around via email and working in sequence eeeeeverything draaaags oooout foreeever.
Packt promised I had 3 months to write and then there'd be a 3 month editing process.
We blew past that because I'm a slow writer, but in June I thought the book was done. We'd spent 3 months writing and 3 months editing.
Then in the end of August I got technical feedback. Oh yeah.
Yes editors are people too and they have other shit to do than care about my book and I'm really happy that one guy in particular (@kmrhb) has taken great care to leave a comment next to almost every single paragraph ... but still.
Apparently a big part of the main editor's job is merging all the documents everyone sends her.
I'm not sure how that works, but a lot of the comments I got in late August are dated to early July. Hm.
If you ever write a book, please use a better tool. Write it in a textual format - markdown works well - and use something that shows diffs and helps you merge stuff and lets people comment without having to wait for you to finish.
Draft looks like it's got a lot of those features. I've had great results with Github for my other book. Readers have sent me typo fixes that I can just merge!
Whatever you do, don't write a book in .doc.
Learned something new?
Read more Software Engineering Lessons from Production
I write articles with real insight into the career and skills of a modern software engineer. "Raw and honest from the heart!" as one reader described them. Fueled by lessons learned over 20 years of building production code for side-projects, small businesses, and hyper growth startups. Both successful and not.
Subscribe below 👇
Software Engineering Lessons from Production
Join Swizec's Newsletter and get insightful emails 💌 on mindsets, tactics, and technical skills for your career. Real lessons from building production software. No bullshit.
"Man, love your simple writing! Yours is the only newsletter I open and only blog that I give a fuck to read & scroll till the end. And wow always take away lessons with me. Inspiring! And very relatable. 👌"
Senior Mindset Book
Get promoted, earn a bigger salary, work for top companiesLearn more
Have a burning question that you think I can answer? Hit me up on twitter and I'll do my best.
Who am I and who do I help? I'm Swizec Teller and I turn coders into engineers with "Raw and honest from the heart!" writing. No bullshit. Real insights into the career and skills of a modern software engineer.
Want to become a true senior engineer? Take ownership, have autonomy, and be a force multiplier on your team. The Senior Engineer Mindset ebook can help 👉 swizec.com/senior-mindset. These are the shifts in mindset that unlocked my career.
Curious about Serverless and the modern backend? Check out Serverless Handbook, for frontend engineers 👉 ServerlessHandbook.dev
Want to Stop copy pasting D3 examples and create data visualizations of your own? Learn how to build scalable dataviz React components your whole team can understand with React for Data Visualization
Did someone amazing share this letter with you? Wonderful! You can sign up for my weekly letters for software engineers on their path to greatness, here: swizec.com/blog
By the way, just in case no one has told you it yet today: I love and appreciate you for who you are ❤️