novel writing version control

• Nov 10, 2021

Saving Your Manuscript: Why Version Control Is Essential

When you delete something big from your manuscript, like a scene or even a chapter, where does it go? Do you cut and paste it into another file just in case you need it later? Do you just delete it and let it dissolve into the ether? Do you keep separate versions of your book, say, for each new draft? Or do you just keep working on the same file for the life of your book?

While I’m a fairly organized and generally minimalistic person with my objects, I actually advocate for never permanently deleting anything when it comes to your writing . In this post, I’ll be outlining why keeping all the versions of your manuscript separate and safe is essential to your writing process.

What’s version control?

Version control allows you to keep track of all changes to a document throughout its history . That way, if you want to reverse a change you make in a later version, it’s easy to go back to the original.

When writing a book, version control often looks like saving a separate file for each draft or editing phase of your manuscript. For example, you may have the following different files on your computer:

mynovel_draft1.docx

mynovel_draft2.docx

mynovel_betareaderversion.docx

mynovel_draft3.docx

mynovel_lineedits.docx

However, you can also use version control to keep track of the different feedback you’re getting from various readers. For example:

mynovel_beta_JohnSmith.docx

mynovel_beta_SarahJones.docx

This makes it easy for you to see at a glance whose feedback you’re about to open up and look at . (I actually use these principles when naming files for clients. So if you send me “mynovel.docx,” I’ll send back “AuthorName_mynovel_edits.docx” when I’m done editing.)

Why do I need all these versions?

If you’ve never used version control before, then I bet that short list of versions above already has your head spinning. What’s wrong with just making changes to the same document?

It’s safer to change your mind.

Let’s say you decide that, in the second draft of your novel, you need to get rid of a certain chapter. It’s really info-dumpy, and the story will flow much better without it. So you delete it. But then, as you continue to work on your story a week or so later, you realize that a lot of the info you deleted was actually essential to understanding some of the plot points in the third act. Unfortunately, that entire chapter is now gone—you deleted it a week ago, and there’s no going back now. You’ll have to try and remember everything you wrote in that chapter and rewrite all of it from scratch.

In this situation, if you had a “draft1.docx” version of your book to go back to, it would be easy to just copy-paste that chapter back in, or to take bits and pieces of it and Frankenstein’s monster them into various sections of draft 2. Having different versions of your draft saves you from having to rewrite a bunch of material if you happen to change your mind later.

It’s easier to compare.

How about this scenario: You can’t decide if your story works better in first-person or third-person point of view, so you write the first two chapters both ways to see how they turn out. But you wrote them both in the same document, and so you have to keep clicking and scrolling back and forth to compare them. It’s not very efficient, and it’s still hard to make up your mind.

If you had a “1stperson.docx” and “3rdperson.docx” file instead, you could open both at once, side-by-side, and compare the two easily. It would then be easier to also insert scenes from other parts of the book to compare those as well . Keeping separate versions allows you to jump back and forth between them more easily.

It keeps you organized.

So now you’re at the beta reading stage of your revisions, and you’ve just got your draft back from six wonderful beta readers. The only problem? The files all have the same name , so you can’t save them easily to your computer, meaning you have to open each one directly from the email attachment every time. Not only that, but while you’re in the middle of looking at the feedback, you keep forgetting who said what.

If you had a different version of the beta file from each beta reader (i.e. “beta_JackSmith.docx”), then it would be easy to always know whose feedback you’re looking at at any given time, and you’d be able to easily go back to their version of the file to review comments or suggestions. Having different versions of your manuscript for each reader helps you keep feedback separate and more organized.

It helps prevent major story loss.

Have you ever had a file suddenly get corrupted for no reason? That can happen to your manuscript, which is another place where versions come in handy. (Aside from backing up your files, which you should always, always do!) If you have a slightly older version of the story, then yes, you’ll definitely have to redo some work, but you won’t have to rewrite the whole thing from the very beginning .

Tips for version control.

So if all of the above has you convinced, here’s what you can do to keep track of the versions of your manuscript.

Name each separate file clearly.

For example, perhaps you’d name your first draft “mynovel_draft1.docx” and your second draft “mynovel_draft2.docx.”

Keep only one active file at any given time.

Once you’ve started the draft 2 version of your manuscript, don’t edit draft 1 ! When you create a new version, you should not make any further changes to the old versions no matter what. Only work on the most recent version. If you’ve got lots of versions going on, this can get confusing, so it may help to mark the current one as something like “mynovel_draft2_active” so that you can find it easier. (Just don’t forget to delete the “active” once that version isn’t active anymore!)

Make backups of all your versions.

You should always be backing up your files anyway, whether that’s to something physical like an external hard drive or something non-physical like the cloud. Make sure to always back up all the versions of your manuscript , not just the current active version. After all, that’s part of the point—to be able to look back at older versions!

You know you need a new version when…

You want to make any major changes , such as deleting a character or rearranging chapters.

You want to do one giant sweep through the whole manuscript for a certain purpose, such as a read-through focusing only on making your sentences prettier or fixing grammar mistakes.

You’re about to pass your manuscript to someone else to read. Create a specially named version just for them, that way you have a record and don’t have to try and remember if you sent draft 2 or draft 3, for instance.

You get manuscript feedback from others , and they haven’t specially named their versions. Name it for them, for your own organization!

You’re about to reformat your manuscript to send it out to an editor, agent, designer, or other professional .

One last note for non-Word users:

Scrivener allows you to keep versions of your chapters stored right within those chapters. The feature is called Snapshots, and it allows you to save exactly what a chapter looked like before you go in to edit it. If you’re writing in Scrivener and don’t want to create a new project file for each version of your book, then this can be a great tool! (I still recommend creating different versions for your exports, though.)

Google Docs also keeps a version history of documents , and it lets you name the versions separately and make copies of them. There’s even a “Restore this version” button for if you absolutely want to go back to an old version of a doc. If you click on the “Show changes” checkbox, you can see exactly what was changed between versions. This is an excellent tool as well, but I still recommend creating an entirely new doc for sending out to beta readers or your editor(s). Why? Because they can see the version history in Google Docs, too, and you don’t necessarily want that!

I hope this post has helped you understand and consider the importance of version control when writing a novel, plus how to do it effectively. Now go forth and back up your files! And if you have any questions, you can always get in touch by email: [email protected] .

• For Writers

Recent Posts

Ediquette: Should I self-edit my manuscript before sending it to my editor?

Ediquette: How to prepare your manuscript for your editor.

Alpha Readers, Beta Readers, Critique Partners, ARC Readers—What kinds of readers do you need?

• Writing a Novel with Visual Studio Code

Sep 19, 2023

If you’re a software developer who also loves to indulge in novel writing, you might be intrigued to discover that you don’t necessarily need a specialised writing tool. Visual Studio Code, the versatile code editor, can prove to be a surprisingly effective ally in your creative writing endeavours. Let’s delve into how Visual Studio Code can enhance your novel-writing experience.

I’ve explored various writing tools in my quest for one that fits my writing style. I started with Microsoft Word and Google Docs, but I found them lacking when it came to providing a comprehensive view of my narrative structure while keeping the main writing pane front and centre. Then, I briefly ventured into Scrivener, a renowned tool for novelists, but I discovered it was packed with features I didn’t necessarily need or want.

Visual Studio Code comes to the rescue, offering a range of features that make it a powerful tool for novelists right out of the box:

Markdown Support Visual Studio Code seamlessly supports Markdown, a lightweight markup language that allows you to structure your novel with ease. Markdown enables you to incorporate formatting, headers, links, and more into your writing.

Organised Folders Just as you would organise your code projects, you can structure your novel in Visual Studio Code. You can create folders to manage various aspects of your writing project, such as character notes, research findings, templates, plot outlines, character dialogues, and more. Maintain a structured hierarchy to keep your work organised.

The folder structure doesn’t need to follow a specific format as long as the files and folders are in alphabetical order. One example is as follows:

Version Control You can leverage the graphical user interface of your preferred version control system to compare files side by side and maintain a comprehensive history of your novel. In many version control systems, you have the option to tag commits / check-ins, allowing you to assign them a version number. For example, you might have a two-part version number, allocating the major number to represent your draft’s version and the minor number for revisions. This approach also enables you to keep track of the specific versions you share with your editor and others that you share your drafts with.

Pandoc To transform your document into a Word document, you can utilise Pandoc , a utility designed for converting from one document format to another. Pandoc can take your Markdown files, be they chapters or individual scenes, and compile them into a cohesive manuscript.

With Pandoc, you can customise the appearance of your manuscript to your specifications. By providing Pandoc with a custom reference Word document, you can control fonts and page borders. You can also denote when to break the page for new chapters. I use Word’s “Heading 1” style to start my chapters with, and have customised the “Heading 1” style to start with a page break. By default, Pandoc converts Markdown headings into Word headings and displays them accordingly in the resulting Word document. Therefore, when it encounters a single hash symbol in the text, it applies Word’s “Heading 1” style, resulting in a page break.

For reference, a typical Pandoc invocation using a reference document looks like this:

I’ve also written a custom sctipt that compiles a list of markdown files in your manuscript location in alphabetical order and then feed that list to pandoc. It also injects a scene separator between scenes but not if it detects a chapter (a chapter is marked by one hash, which is Heading 1 in markdown, which I reserve for denoting a new chapter in the manuscript). Plus, it also takes care of versioning your work by tagging your commits (works with Git only).

While Visual Studio Code can be a powerful ally for novel writers, it’s important to acknowledge some drawbacks:

Lack of Specialised Writing Tools Unlike dedicated writing software like Scrivener, Visual Studio Code doesn’t offer specialised tools for novelists, such as character and plot management or storyboarding.

No Mobile Support Visual Studio Code is a desktop application for writing code, and there is no version available for Android or iOS devices, limiting your writing flexibility on mobile platforms.

No Built-in Proofreading Visual Studio Code lacks built-in proofreading features. You would need to copy and paste your text into external tools like Grammarly for grammar and spell checking.

No Pandoc Support for Mobile Pandoc is a command-line utility for converting document formats, and it isn’t commonly available as a mobile application.

Visual Studio Code, equipped with its native support for Markdown, folder structuring reminiscent of coding projects, tapping into version control and command-line tools, stands as a powerful and highly adaptable tool for writers who also have a technical background. Nevertheless, it’s crucial to carefully evaluate the benefits and drawbacks while keeping your unique writing requirements and preferences in mind.

Software Developer

GitHub Email

• Preserve commit history when moving files across Git repositories
• Publishing a Jekyll site to a separate Github Pages repository using Github Actions
• Installing the NewRelic .NET agent on an Alpine Docker image
• An implementation of the Capital Controls kata in Python

A Writer’s NeoVim

• 🔥 Transform your Neovim into a full-fledged Integrated Writing Environment (IWE): Write, Edit and World-build at the speed of thought
• 💤 Easily customize and extend your config with lazy.nvim
• 🚀 Stupid fast
• 🧹 Sane default settings and options for writers
• 😻 Eye candy in the form of beautiful color schemes, in dark and light modes, including flavours of Catppuccin, Gruvbox, Nord, NightFox
• 📦 Comes with a wealth of plugins for longform writing, interconnected note-taking (wikis, etc.), and screenwriting. All pre-configured and ready to use

🔎 OVI-WHAT-NOW?

OVIWrite is a NeoVim powered Integrated Writing Environment (IWE) built using LazyVim and 💤 lazy.nvim .

The goal is to make it as easy as possible for writers to start using NeoVim out of the box.

This begs the question: what kind of writer would gravitate towards OVIWrite in the first place? Good question. I spend some time discussing it below.

At first Vim, and now NeoVim, have formed the basis of my dream writing environment. Who even dreams of their writing tools? I have no answers except to say that I do venture outside regularly to touch grass and talk to people - don’t worry.

I wanted a writing tool that ticked these boxes:

• Long form prose (i.e. novels, academic writing, reports, essays)
• Research and note-taking

Screenwriting

• Supported a wide range of plain text standards including Markdown and LaTeX.
• Adaptable to any platform, Unix style OSs (MacOS, Linux) or otherwise (Windows), desktop or mobile, Android or iOS
• Offered the features of traditional word processors (Spell and Grammar checking for instance)
• Offered opinionated quality of life improvements such as Version Control through Git

This is a tall order to ask for word processors. It is why conventional word processing software such as MS Word fails, at least for me.

Granted I wrote my first novel on MS Word, I came to find that it wasn’t extensible enough to scale with my needs, nor was it nimble and fast.

An ideal writing tool should adapt to a writer’s needs at a moment’s notice.

• Get back to working on the novel? Sure, here’s a beautiful LaTeX template for me to work on my novel.
• Write a screenplay? Why not?
• Build an inter-connected network of notes like Obsidian or Notion? Done.

Here are two demos I presented at the NeoVimConf where I presented two early versions of OVIWrite.

• Writing, Editing and World-Building at the Speed of Thought (version 0.1) (Nov 2021)
• Vimkipedia: Or How I Built my Second Brain Using Vim (version 0.2) (Dec 2022)

Essentially, these two talks served as early demos of OVIWrite versions 0.1 and 0.2. However, the eagle-eyed among you will notice I used a combination of Vim and NeoVim during these talks. This was because I couldn’t get some Vim-specific plugins to work with NeoVim, a problem that has since been solved.

This version of OVIWrite is built entirely in Lua, and follows the modular structure of LazyVim.

This is version 0.4 (Dec 11th 2023)

Nomenclature

You will notice that Vim and NeoVim are used interchangeably here. This might appear confusing at first so let’s be clear:

• Vim is a text editor whose roots go back to the early 80s. Its creator was the late Bram Moolenaar . Among its many innovations that have aged well in its four decades is the notion of Modal Editing . Modal editing text editors like Vim change your keyboard functionality based on what mode you are in.
• Vim allows for a number of modes: Normal, Insert, Visual, Command and Replace modes.
• NeoVim is a ‘fork’ of Vim, a modern interpretation of what Vim can be. It’s about a decade old and is maintained by a core group of maintainers, led by Justin M. Keyes . It inherits Vim’s modal-editing philosophy, but has moved to a modern programming language: Lua
• Both Vim and NeoVim have rich eco-systems that extend the editor’s functionality to suit the exact needs of the user.
• These eco-systems are thriving as a result of tireless plugin makers, some of whom have created, and continue to maintain, dozens of plugins
• Most plugins are created for explicit software engineering/programming tasks. A few plugins are created for writing of prose or other text manipulation tasks outside of conventional programming
• OVIWrite is based on NeoVim; specifically it is based on an existing NeoVim starter kit LazyVim
• OVIWrite uses a curated list of writing-centric plugins along with some plugins that are traditionally for software engineering tasks, but whose functionality has application in the work of writers or anyone working with large chunks of text

👨💻 AUDIENCE

I hear you: Who is this for?

Personally, I think of Vim/NeoVim as analogous to a musical instrument, say a piano. Are pianos meant only for world-class pianists? No.

The first interaction with a piano is often messy, confusing and overwhelming; stick with it, and there is a little bit of magic waiting to be experienced.

This mindset has helped immensely in scaling the steep learning curve that comes with Vim’s modal editing philosophy.

But unlike me, writers like you don’t have to invest the additional time in learning how to wrangle Vim to be a tool for writing. All you need is a couple of weeks practicing Vim motions and understanding its different modes.

Once you overcome that hurdle, install OVIWrite and get writing!

I am not a tech person. I don’t know programming or how to read code. This looks overwhelming. Is this for me?

Only you can answer that. I don’t consider myself to be a tech person - tech savvy, yes but I can barely read code myself.

So no lies here: (Neo)Vim motions and modal editing requires a rewiring of our writer brains. But the good news is that it shouldn’t take more than two weeks of 10-15 minutes a day. Vimtutor , built into Vim, is the best place to practice.

There is also some steep knowledge acquisition required to understand NeoVim’s internal nuts and bolts. This is only required if you want Vim to work exactly as you want it to. I did, which is why I set off on this journey three years ago.

OVIWrite offers a higher floor from which to start your own explorations.

You don’t need to know how to program or read Lua code, to use OVIWrite. All that work has been done for you. Nothing is stopping you from peaking behind the curtains at the source code. Add or modify the code as you see fit if you are feeling extra adventurous

More good news: Vim is almost 40 years old. The community has been around for decades, and have extensively documented tips, tricks and hacks. Chances are the error message you are seeing has been seen countless times before by countless people, and in all those occasions there was an experienced Vim user helping out a new-comer. I can speak from experience on this last fact.

Once again, thinking of OVIWrite as akin to a musical instrument might be the best way to overcome its apparent complexity; instead of music, OVIWrite is purpose-built for efficient (and damn near magical) textual recall, creation and manipulation.

Being tech-savvy will make this easier but it is not a requirement.

Being patient is.

Heavy Googling is (as any programmer will tell you).

Rewarding Long-Term Benefits:

I can only offer personal anecdotes here in lieu of a more scientific approach.

I have steadily become very productive in the three years since my first encounter with Vim.

The procrastination associated with writing has disappeared, and I believe part of that is because I don’t have to struggle through the bloated mess that is MSWord.

Editing, too, has become a joy because editing is Vim’s superpower. Combined with the curated plugins included in OVIWrite, you should be writing, editing and world-building at the speed of thought!

The Promise of Plain Text

Most writers writing on word processors use Rich Text. Rich Text, for all its benefits, does come back with significant drawbacks: vendor lock-in being a primary concern. Rich Text also doesn’t age well. Rich text’s older, less glamorous kin, Plain Text ages better, doesn’t lock you into a vendor, and gives you the freedom to choose the tools that are suited for your work. For more, read The Case for Plain Text

Embracing Git For Writing

Git is a robust version control system initially designed for software development, and has emerged as an invaluable asset for my writing workflow. Really, I think it’s damn near criminal that we don’t teach writers Git at some point in their developmental stage. Read more here

• Write, Edit, World-Build at the speed of thought : OVIWrite liberates your writing process by focusing on plain text , freeing you from vendor lock-in for unparalleled flexibility.
• Effortless Collaboration : Built-in version control using LazyGit ensures seamless tracking and collaborative writing experiences
• Versatile Syntax Support : From LaTeX to Markdown and from Org-mode to Fountain, enjoy comprehensive syntax support for every writing endeavor—from reports and essays to screenplays and personal wikis
• Flawless Composition : Spellcheck, thesaurus, and dictionary tools integrated for a seamless writing experience
• Built-in Translator : A built-in translator effortlessly translates between English and a diverse range of languages, breaking down language barriers with ease.

I use OVIWrite for the following use-cases:

• LaTex documents for my novels and academic writing
• Fountain files for writing scripts and screenplays
• Markdown and Org Mode files for writing simpler reports and blogs
• Vim-wiki for my personal Zettelkasten

See screenshots below.

I needed an Integrated Writing Environment, a toolkit that was fast, yet extensible enough to scale with a writer’s changing requirements.

I spent a lot of time writing on diverse IDEs to get a sense of what I wanted out of my IWE; in fact, my inspirations for OVIWrite were VSCode , PyCharm and indeed the many Vim/NeoVim inspired distros like NVChad , LunarVim , and Doom Emacs .

I currently run this version of OVIWrite on my Mac (MacOS Sonoma 14.1.2), Linux (popOS 22.04 on my desktop, and Ubuntu Server 22.04 on my server), and Android 12 (OxygenOS 12.1 on a OnePlus 7T). I don’t have a Windows machine to test at the moment. iPad testing is ongoing. I am fairly confident that OVIWrite will work pretty great on a semi-recent Android tablet (I don’t have an Android tablet to test), as long as Termux is installed.

📺 SCREENSHOTS

Note: The screenshots below show a variety of color schemes at play: Nightfox, DawnFox and NordFox. Also included in the config: Gruvbox and flavours of Catppuccin. I’ve included my favourite color schemes; users are, of course, free to add whatever color scheme that is available in the NeoVim ecosystem.

Long-form Writing

• Longform Writing; LaTeX

• Longform Writing; Org-Mode

• Longform Writing; Markdown

• Screenwriting in Fountain format

Note-taking and Research

• Zettelkasten

INSTALLATION

⚡️ requirements.

• Neovim >= 0.8.0 and its associated dependencies (needs to be built with LuaJIT )
• Git >= 2.19.0 (for partial clones support)
• a Nerd Font (optional but highly recommended)
• LaTeX compiler

Installing OVIWrite

Detailed Installation instructions can be found on our wiki

You can download the zip file containing all the source code. Copy it into the appropriate folder.

Unix Systems (Linux and MacOS)

Command Prompt

Keyboard Shortcuts

OVIWrite uses which-key.nvim to help you remember your keymaps. Just press any key like <space> and you’ll see a popup with all possible keymaps starting with <space> .

• default <leader> is <space>

🤝 CAN I CONTRIBUTE?

Please, and thank you.

Contributions are encouraged. Feel free to make a pull request with modifications. If you want to contribute at a deeper level - maybe even forking NeoVim for writing outright - do reach out to me. I will be happy to collaborate and learn from the community.

• @MiragianCycle , Theena Kumaragurunathan
• @mhegreberg , Mark Hegreberg

🎁 ACKNOWLEDGEMENTS

None of this would be possible without the contributions of the entire Vim and NeoVim eco-systems. Please contribute in anyway, financial or otherwise, to these incredible projects and the tireless people who maintain them.

Additional Reading

• Friction: Or How I Learnt to Stop Worrying and Love Vim
• Configuring Vim as a writing tool
• Every year is someone’s year of Linux Desktop
• Using Git Version Control as a writer

Chris Aldrich

Musings of a Modern Day Cyberneticist

Git and Version Control for Novelists, Screenwriters, Academics, and the General Public

Marginalia and revision control.

At the end of April, I read an article entitled “ In the Margins ” in the Johns Hopkins University Arts & Sciences magazine.  I was particularly struck by the comments of eminent scholar Jacques Neefs on page thirteen (or paragraph 20) about computers making marginalia a thing of the past:

Neefs believes contemporary literature is losing a valuable component in an age when technology often precludes and trumps the need to save manuscripts or rough drafts. But it is not something that keeps him up at night. ‘The modern technique of computers and everything makes [marginalia] a thing of the past,’ he says. ‘There’s a new way of creation. Some would say it’s tragic, but something new has been invented. I don’t consider it tragic. There are still great writers who write and continue to have a way to keep the process.’

I actually think that he may be completely wrong and that current technology actually allows us to keep far more marginalia! (Has anyone heard of digital exhaust ?) The bigger issue may be that many writers just don’t know how to keep a better running log of their work to maintain all the relevant marginalia they’re actually producing. (Of course there’s also the subsequent broader librarian’s “ digital dilemma ” of maintaining formats for the future. As an example, thing about how easy or hard it might be for you to read that ubiquitous 3.5 inch floppy disk you used in 1995.)

A a technologist who has spent many years in the entertainment industry, I feel compelled to point everyone towards the concept of revision control  (or version control) within the realm of computer science.  Though it’s primarily used in tracking changes in computer programs and is often a tool used by large teams of programmers, it can very easily be used for tracking changes in almost any type of writing from novels, short stories, screenplays, legal contracts, or any type of textual documentation of nearly any sort.

Example Use Cases for Revision Control

As a direct example, I’m using what is known as a Git repository to track every change I make in a textbook I’m currently writing.  I can literally go back and view every change I’ve made since beginning the project, so though I’m directly revising one (or more) text files, all of my “marginalia” and revisions are saved and available.  Currently I’m only doing it for my own reference and for additional backup not supposing that anyone other than myself or an editor possibly may want to ever peruse it.  If I was working in conjunction with otheres, there are ways for me to track the changes, edits, or notes that others (perhaps an editor or collaborator) might make.

In addition to the general back-up of the project (in case of catastrophic computer failure), I also have the ability to go back and find that paragraph (or multiple pages) I deleted last week in haste, but realize that I desperately want them back now instead of having to recreate them de n0vo.

Because it’s all digital, future scholars also won’t have problems parsing my handwriting issues as has occasionally come up in differentiating Mary Shelley’s writing from that of her husband in digital projects like the Shelley Godwin Archive . The fact that all changes are tracked and placed in a tree-like structure will indicate who wrote what and when and will indicate which changes were ultimately accepted and merged into the final version.

Screenplays in Hollywood

One particular use case I can easily see for such technology is tracking changes in screenplays over time.  I’m honestly shocked that every production company or even more likely studios don’t use such technology to follow changes in drafts over time. In the end, doing such tracking will certainly make Writers Guild of America (WGA) arbitrations much easier as literally every contribution to a script can be tracked to give screenwriters appropriate credit. The end results with the easy ability to time-machine one’s way back into older drafts is truly lovely, and the outputs give so much more information about changes in the script compared to the traditional and all-too-simple (*) which screenwriters use to indicate that something/anything changed on a specific line or the different colored pages which are used on scripts during production.

I can also picture future screenwriters using services like GitHub as platforms for storing and distributing their screenplays to potential agents, managers, and producers.

Redlining Legal Documents

Having seen thousands of legal agreements go back and forth over the years, revision control is a natural tool for tracking the redlining and changes of legal documents as they change over time before they are finally (or even never) executed. I have to imagine that being able to abstract out the appropriate metadata in the long run may actually help attorneys, agents, etc. to become better negotiators, but something like this is a project for another day.

In addition to direct research for projects being undertaken by academics like Neefs, academics should look into using revision control in their own daily work and writings.  While writing a book, paper, journal article, essay, monograph, etc. (or graduate students writing theses) one could use their own Git repository to not only save but to back up all of their own work not only for themselves primarily, but also future scholars who come later who would not otherwise have access to the “marginalia” one creates while manufacturing their written thoughts in digital form.

I can easily picture Git as a very simple “next step” in furthering the concept of the digital humanities as well as in helping to bridge the gap between C.P. Snow’s “two cultures.”  (I’d also suggest that revision control is a relatively simple step one could take before learning a particular programming language, which I think should be a mandatory tool in everyone’s daily toolbox regardless of their field(s) of interest.)

Start Using Revision Control

“But how do I get started?” you ask.

Know going in that it may take parts of a day to get things set up and running, but once you’ve started with the basics, things are actually pretty easy and you can continue to learn the more advanced subtleties as you progress.  Once things are working smoothly, the additional overhead you’ll be expending won’t be too much more than the old method of hitting Alt-S to save one of your old Word documents in the time before auto-save became ubiquitous.

First one should start by choosing one of the myriad revision control systems that exist.  For the sake of brevity in this short introductory post, I’ll simply suggest that users take a very close look at Git because of its ubiquity and popularity in the computer science world and the fact that it includes a tremendously large amount of free information and support from a variety of sites on the internet. Git also has the benefit of having versions for all major operating systems (Windows, MacOS, and Linux). Git also has the benefit of a relatively long and robust life within the computer science community meaning that it’s very stable and has many more resources for the uninitiated to draw upon.

Once one has Git installed on their computer and has begun using it, I’d then recommending linking one’s local copy of the repository to a cloud storage solution like either GitHub or BitBucket .  While GitHub is certainly one of the most popular Git-related services out there (because it acts, in part, as the hub for a large portion of the open internet and thus promotes sharing), I often recommend using BitBucket as it allows free unlimited private but still share-able repositories while GitHub requires a small subscription fee for keeping one’s work private. Having a repository in the cloud will help tremendously in that your work will be available and downloadable from almost anywhere and because it also serves as a de-facto back-up solution for your work.

I’ve recently been playing around with version control to help streamline the writing/editing process for a book I’ve been writing. Though Git and it’s variants probably seem more daunting than they should to the everyday user, they really represent a very powerful tool. I’ve spent less than two days learning the basics of both Git and hosted repositories (GitHub and Bitbucket), and it has been more than well worth the minor effort.

There is a huge wealth of information on revision control in general and on installing and using Git available on the internet, including full textbooks . For the complete beginners, I’d recommend starting with The Chronicle’s “ A Gentle Introduction to Version Control .” Keep in mind that though some of these resources look highly technical, it’s because many are trying to enumerate every function one could potentially desire, when even just the basic core functionality is more than enough to begin with. (I could analogize it to learning to drive a car versus actually reading the full manual so that you know how to take the engine apart and put it back together from scratch. To start with revision control, you only need to learn to “drive.”) Professors might also avail themselves of the use of their local institutional libraries which may host small sessions on learning such tools, or they might avail themselves of the help of their colleagues or students in the computer science department. For others, I’d recommend taking a look at Git’s primary website. BitBucket has an excellent step-by-step tutorial (and troubleshooting) for setting up the requisite software and using it.

What do you use for revision control?

I’ll welcome any thoughts, experiences, or additional resources one might want to share with others in the comments.

Published by

I'm a biomedical and electrical engineer with interests in information theory, complexity, evolution, genetics, signal processing, IndieWeb, theoretical mathematics, and big history. I'm also a talent manager-producer-publisher in the entertainment industry with expertise in representation, distribution, finance, production, content delivery, and new media. View all posts by Chris Aldrich

22 thoughts on “Git and Version Control for Novelists, Screenwriters, Academics, and the General Public”

Version control is the bane of my existence.

Jason Govern I had you in mind as I was writing this…

@ChrisAldrich I haven’t, but I haven’t asked so they certainly could be.

> doing such tracking will certainly make Writers Guild of America (WGA) arbitrations > much easier as literally every contribution to a script can be tracked to give screenwriters > appropriate credit.

Actually that’s not true. The only version that matters, are the versions turned in, and those are not the responsibility of the Production Company. Also, there are limited number of credits on screenplays.

Some screenplays have upwards of 30 different writers, only 2 will get any credit (3 if there is a team, and a single writer; 4 if two teams work on the scripts; but that’s it). Them’s the rules!

Also, some changes to the screenplay would NOT show up in the drafts. e.g. I come up with a story, and sell that story to a production company; they hire a writer to write the screenplay. I get a STORY BY credit, the writer gets WRITTEN BY. If I wrote a book, I would get BASED ON BOOK BY credit.

It is possible to have up to 6 writers on a screenplay, but VERY unlikely.

I forgot to include this above.

> I can also picture future screenwriters using services like GitHub as platforms > for storing and distributing their screenplays to potential agents, managers, and producers.

Not going to happen. it provides no value to writer, agents, or production companies. it’s not even close to secure enough to be considered.

As a former programmer, who gets Version Control, and now writes; it’s a non starter to use GITHub. It may excite the geeks, but for us, we need it to make our lives easier. it doesn’t.

Mark, I’m guessing you’ve never been involved in a WGA arbitration for credit have you? With many productions being in development for an average of 10 years, there can often be over 30 drafts with literally dozens of writers or writing teams not to mention the specific punch ups by writers who contractually don’t want credit. While in the end only a very small handful are going to get credit, the credit is based on who wrote what and how much of it. This is where having the ability to go back and see who actually wrote which particular lines could make the process much simpler than some of the shenanigans that currently goes on in assigning credit. The credit assignation is generally done by the WGA and it’s fairly routine for almost all of them to be arbitrated. Because of the way credit is given, it’s usually fairly difficult for the first writer(s) to not get at least partial shared credit. Generally the paid drafts that are handed into the studio are the ones which are used, though depending on the legal paper trail, it can sometimes be the drafts handed into the production company when there hasn’t been a studio directly involved in the overall process.

Sadly, version control isn’t quite simple enough to make it a thing that everyday people might use yet, but the day is certainly coming…

GitHub is also, by it’s commercial nature, a more open platform, so security isn’t as good as it is with others like Bitbucket which have more privacy and distribution controls. It would more likely be these more secure/controllable platforms that would be used for near-instantaneous delivery or pre-approved access for scripts within the entertainment community. There’s certainly a much better way to improve this type of business information flow within the community.

@ChrisAldrich @biorxivpreprint I do use version control. Nonetheless Google is easier.

Part of my plans to (remotely) devote the weekend to the IndieWeb Summit in Portland were hijacked by the passing of Muhammad Ali. Wait… What?! How does that happen? A year ago, I opened started a publishing company and we came out with our first book Amerikan Krazy in late February.  The author has a small backcatalogue that’s out of print, so in conjunction with his book launch, we’ve been slowly releasing ebook versions of his old titles. Coincidentally one of them was a fantastic little book about Ali entitled Muhammad Ali Retrospective , so I dropped everything I was doing to get it finished up and out as a quick way of honoring his passing. But while I was working on some of the minutiae, I’ve been thinking in the back of my mind about the ideas of marginalia , commonplace books , and Amazon’s siloed community of highlights and notes. Is there a decentralized web-based way of creating a construct similar to webmention that will allow all readers worldwide to highlight, mark up and comment across electronic versions of texts so that they can share them in an open manner while still owning all of their own data? And possibly a way to aggregate them at the top for big data studies in the vein of corpus linguistics? I think there is… However it’ll take some effort, but effort that could have a worthwhile impact. I have a few potential architectures in mind, but also want to keep online versions of books in the loop as well as potentially efforts like hypothes.is or even the academic portions of Genius.com which do web-based annotation. If anyone in the IndieWeb, books, or online marginalia worlds has thought about this as well, I’d love to chat.

Leave a Reply Cancel reply

Your email address will not be published. Required fields are marked *

Notify me of follow-up comments by email.

Notify me of new posts by email.

To respond to a post on this site using your own website, create your post making sure to include the (target) URL/permalink for my post in your response. Then enter the URL/permalink of your response in the (source) box and click the 'Ping me' button. Your response will appear (possibly after moderation) on my page. Want to update or remove your response? Update or delete your post and re-enter your post's URL again. ( Learn More )

Productivity

Jumpstart Your Next Writing Project with Scrivener: The Writing App for Organized, Efficient Writers

Writing is hard.

Whether writing the next Great American Novel or keeping up with your blog's demand for new content, you have a lot to juggle. Research, outlines, notes, drafts, edits, publishing—let alone the actual writing process.

Scrivener makes it easier. Made by writers for writers, Scrivener is designed to be the only app you need open while you write. Boasting a versatile suite of organizational tools and outlining and storyboarding views, this app streamlines the writing process from idea to published work, and keeps everything organized so you can just write.

That said, Scrivener can be a little overwhelming when you first get started. I personally had several false starts with Scrivener before I finally fell totally in love with it—now I use it for everything. Not to worry, there are really only three sets of tools you need to understand in order to use Scrivener productively.

This article won't give you all the ins and outs of Scrivener’s many features and uses. It will instead help you hit the ground running with Scrivener and its core features so you can take your writing from idea to polished draft to published piece in one of the most robust writing apps available today.

Why Scrivener?

Originally designed for novelists, Scrivener has been embraced by all kinds of writers, from students to professional bloggers. The main appeal? Its power to organize your writing.

Compared to word processors like Word or Google Docs, Scrivener is a whole different ballgame with its focus on managing your writing. Imagine the organizational power of Evernote, combined with the powerful simplicity of a Word document, minus the inconveniences of using both apps together.

Break your project into multiple documents to avoid endless scrolling (don't worry, Scrivener will automatically compile them all into one). Edit freely without the hassle of tracking changes—Scrivener lets you quickly save and browse "Snapshots" of your project history. Switch between Document, Outline, and Corkboard modes to refocus your attention during the lifecycle of your project.

Everything in Scrivener is designed to help you compartmentalize and organize your work, breaking down both the writing and editing processes into focused, manageable chunks.

Scrivener's great for business writing, too. Check out some of these third-party Scrivener templates from All Indie Writer:

Get Started with Scrivener

First, you'll be prompted to choose a template and name your file (don’t worry if your project doesn’t fit any of the default options).

Scrivener will then greet you with a familiar word processor interface, with rich text formatting options in the toolbar above the writing pane.

There are a ton of other features you can use in Scrivener to organize your writing notes and research, outline your article or book, and more. For now, let's look at the most important Scrivener features to take your writing from draft to finished piece. It all comes together in what Scrivener calls "the Binder"—the collection of folders that contain all the work related to a writing project.

Depending on whether or not you use a pre-existing template, you’ll have at least three folders in your Binder to begin with: Draft, Research, and Trash.

Draft is the folder where your main project lives. This is the main folder to export at the end of the project, the place where you’ll keep the writing part of your writing. For example, if she were to write the next Harry Potter book in Scrivener, J.K. Rowling would likely add a folder for each chapter within the "Draft" folder. Each scene would be its own document to make revisions easier (more on that later).

Research is a convenient folder to keep any notes, references, or web pages you need for your project.

To add more documents and folders to the Binder, you can either click the + or gear symbols in the toolbar on the bottom of the Binder, or right-click anywhere in the Binder to add a new item.

The Inspector

The "Inspector" tools will be in a panel on the far right or can be toggled with the blue button on the top right side of your screen. This panel is the central nervous system for your documents, giving you access to notes, references, past document versions, and more—all quickly available while you write. These are the different tools you’ll find in this pane:

Synopsis. Jot ideas or a description for your document.

Document Notes. The scratch pad for your document, sitting just beneath the main Inspector pane. Here, you have as much room as you need to make plain text notes and view them as you write. For example, I use these notes to jot down a micro-outline for the document which I can refer to while writing.

References. Keep track of references for your document or project in this part of the Inspector. You have three options for references in Scrivener: Add an internal reference (a note or another document), link to another file on your computer, or link to a web page.

How to Organize a Project in Scrivener

While you can certainly use Scrivener for smaller writing projects or other projects where you'd use a word processor, its real strength is in its capacity to organize large writing projects. From novels to non-fiction to thesis projects to long-form articles, Scrivener is an excellent tool for gathering a lot of thoughts and information into something cohesive and usable.

Advanced Binder

The Binder is the main way you'll navigate your Scrivener project, but it’s also one of the Scrivener’s best organization tools. If you choose a template for your project, the Binder will come with a few pre-created folders, but don’t let those limit your creativity.

Outline your project by creating new documents for each section. While it’s essential to split novels or nonfiction book projects into chapters and scenes, it’s also helpful for projects like longform articles. Split each section into its own document so you can more easily manage your editing process.

Create as many folders as you want, or simply drag and drop relevant notes or research onto an existing document to make that document the parent content, a form of folder where the folder itself includes text, too. (For example: a novelist may include backstory notes or plot ideas as child files of a character document.)

Note that this is not actually a second Binder—if you create a new document within a Collection, it will create a new folder in your Binder. You also have to manually add documents and folders to a Collection. Collections are excellent for organizing notes and research. As another example, you could create one Collection per major chapter or section of a book/eBook, then add the chapter document(s) and all notes and research into the Collection, making them easily accessible.

Since you can collapse and reorganize the Binder and Collections however you want, it helps to play around with different folder systems so you can find something that fits your writing process well. You can also create and arrange folders specifically to use with Scrivener’s main outlining tools, Corkboard Mode and Outline Mode.

Corkboard Mode

Scrivener provides three ways to view your documents: The default Document editor, along with Corkboard and Outline views. Both Corkboard and Outline modes give you a visual way to outline and review your project, but each serves a different purpose.

Corkboard provides you with a bulletin-board view of a selected folder. Every document in the folder is displayed on this board as an index card. By default, the index cards display your document’s title, synopsis, and a color marker for your labels. You can also adjust Corkboard settings to display keyword color markers, status stamps, and card number.

Create storyboard folders in this mode specifically for the purpose of rearranging ideas and drafts corkboard-style, or outline your main draft folder using this view mode.

Outline Mode

Outline Mode serves the same purpose as Corkboard Mode, but with more classic visuals. Outline displays the documents in a selected folder in an almost spreadsheet-like format. As a default, the outline displays document title, document synopsis, labels, and status. Customize this view by adding or removing any one of 20 different field types, such as word count, target progress, keywords, and many more.

While Corkboard Mode is fantastic for brainstorming and initially organizing or storyboarding a project, Outline Mode gives visibility to a lot of important data for writers who are drafting or revising.

Keywords & Custom Metadata

Two of Scrivener’s oft-overlooked features, Keywords and Custom Metadata are powerful tools to help you manage longer projects. These are both tied into Scrivener’s search function and allow you to quickly find documents based on custom criteria.

Keywords can be added to documents to group themes, settings, and ideas. Add keywords from within the Inspector panel (look for the key icon). You can create and add as many keywords as you want, and you can organize keywords into keyword hierarchies. (Bear in mind, however, that keyword hierarchies are for organization only—search will only pick up the keyword itself, not any parent keywords.)

Novelists might use keywords to keep settings consistent—for example, the keyword "Hogwarts Main Hall" could be applied to every scene that takes place in that location, making it easy to check consistency in revisions. Or, you might use it for something even broader: "Character Moment," "Harry’s History," or "Major Plot Moments."

Custom Metadata adds another dimension to Scrivener’s search by allowing you to create custom data fields. You can then search or review documents with these fields specifically. The best part is that this metadata is completely customizable.

Non-fiction writers might use custom metadata to keep track of sources referenced (even source material chapter and page number!) for a particular document, to make it easier to find, reference, and fact check later.

Novelists might use these fields to track specific characters or settings in tandem with keywords. For example, you might have the keyword "Character Moment" for a certain scene, and, in a custom "Character" field, have "Hermione Granger."

You may be wondering right about now— when should I use keywords and when should I use custom metadata?

Honestly, there’s no right answer. In some ways, these functions are even interchangeable (you could easily create the keyword "Character Moment: Hermione" instead of using keywords and custom metadata). Really, it’s up to you and how you want to organize your documents/scenes, chapters, and notes. Figure out the themes, moments, arcs, or details that are most important for you to track, then create a keyword or metadata system that makes it easy for you to find those later.

How to Write Distraction-Free in Scrivener

A writer loves nothing more than hitting their flow—that state where you’re totally consumed with \ writing and everything just works. Yet for most of us, hitting flow is difficult.

Scrivener seeks to help writers achieve—and remain in—their flow state by adding tools and layouts to help keep you as focused on your project as possible.

Composition Mode

One of Scrivener’s best features is its composition mode. You can toggle this mode with the arrow button in the main toolbar above your writing screen. In Composition Mode, your document takes over the whole screen, dimming the rest of your screen or project to help you focus. The zoom level and width of your writing pane are adjustable, so play around and find the size that works for you.

Composition Mode works well as a minimalistic editor, removing distractions between you and your writing. You can even add an image background behind the text editor that inspires or relaxes you.

Then, like most features in Scrivener, Composition Mode can be adjusted to become more of a dashboard for your project, adding control and project visibility even while keeping your attention on your writing.

Extra features may seem like they’d defeat the purpose of a composition mode, but the features Scrivener allows in this make sure you spend less time hopping in and out of Composition Mode.

When in Composition Mode, hover at the bottom of your screen to activate the toolbar. Here you’ll find options for expanding certain features, as well as for adjusting your visuals.

The Inspector pop-up sits beside your main document and provides you with quick access to details like your synopsis, comments, document notes, references, pictures, and more. So whether you need to reference notes, or add notes or comments as you write, you can quickly do so without leaving Composition Mode.

Quickly monitor or add Keywords via a pop-up window, which you can leave floating next to your writing pane for quick reference.

Finished and ready to move to the next scene or section (or need to check on some research)? Use the Go To menu to move between documents from within Composition Mode.

A quick tap on Cmd/Ctrl + Shift + T brings up your Project Targets. This window lets you know the total word count of your document, as well as how many words you’ve written during this particular session. You can adjust this window to reflect wordcount goals (total and per session), as well as deadlines.

Scrivener also has a Typewriter Mode, which will make your text scroll up while you write, keeping your focus always on the same line. You can toggle this mode quickly with Ctrl + Cmd + T on a Mac, or from the Formatting -> Options menu on Windows.

Keep Your Research Close

For most writers, it’s natural to bounce between your word processor and your browser to double check a source, reference an image, or find the right quote. Problem is, even that "productive" hop onto the Internet often leads down a rabbit trail of clicks and distractions.

Scrivener breaks that pattern with tools to keep your research close at hand. Every project comes with a "Research" folder, where you can keep and refer to live web pages. Simply right-click on the Research folder, hover over "Add" and select "Web Page." Once you add the page, it will be available in Scrivener, even if you go offline.

Writing with Split Panes

Think it would be great if you could have your research pulled up alongside your draft? Scrivener thinks so too. Under the View menu, in the dropdown Layout , you’ll find the option to split the writing pane either horizontally or vertically.

This gives you two different writing screens you can navigate. Click once in the pane you want to navigate, then click in the Binder to select a web page, note, or document. You can also do this with folders, then select a Corkboard or Outline View Mode to view your project outline while you write.

Version Control

"Kill your darlings" is common editing advice for fiction writers, meaning you shouldn't get too attached to any one character, chapter, or even paragraph. This means that sometimes, you’ll have to delete a lot of great stuff for the sake of the whole.

Of course—who’s to know if you’ll actually need those paragraphs later? While you could try copy/pasting anything into a different document before editing, or using "Save As," Scrivener has a simpler solution.

With Snapshots, you can instantly save the current version of the document working in (in its entirety), and refer back to it later. This version control system is literally as easy as Cmd/Ctrl + 5 . (To save a snapshot with a title to quickly find that darling you killed, use Shift + Cmd + 5 on Mac, or Ctrl + Shift + 5 on Windows.)

To view your Snapshots, open the Inspector and, in the Inspector mini-toolbar, select the camera icon. This will show you all the snapshots you’ve taken for that document. You can review the previous version in the Inspector pane, or you can choose "Compare" and see all the differences between the selected Snapshot and your current version. If you need to return to an earlier version, you can Roll Back a document to a Snapshot version with just one click.

How to Format an Article or eBook in Scrivener

One of the most time consuming parts of a project can be the formatting. Whether it’s just a matter of rich text vs Markdown, or whether you are doing a project that requires complex formatting—such as a novel or a thesis—Scrivener is here to help.

Markdown format has gained a lot of popularity in recent years due to its ease of use—once you learn the formatting codes, it’s easy to add formatting without distracting yourself from your writing.

But not all blog platforms accept Markdown formatting (and whose boss would want to see a report full of hashtags and asterisks)? Luckily, Scrivener makes it easy for you to write in Markdown and convert to other formats with just a couple of clicks.

When your project is done, go to File > Compile and then choose from the dropdown "Compile For" menu (shown above) to export to popular formats like Rich Text or HTML, as well as LaTex and Flat XML.

But hey, if Ctrl/Cmd + B is still more natural for you, don’t worry. Just use the standard keyboard shortcuts or the formatting toolbar to add the style you want, then Scrivener makes it easy to convert bold and italic formatting from rich text to Markdown or any other format you need.

Export & Publish

So you’ve reached the end of your project. Now what? Well, that depends on the type of project you wrote, and the final form you want it to be in. Scrivener supports several different formats, from novel layouts to annotated books to simple document formats.

You can either choose from one of these presets, or create your own customized compile to adjust settings like formatting, layout, fonts, and page settings.

There are a lot of options to play with, and the details are beyond the scope of this guide. But don’t worry—if you want to simply export your work as a unified document, you can.

For Format As choose "Original", then at the bottom of the window, in Compile For choose "Microsoft Word 97-2004" for a simple .doc format. (Choose .docx or PDF in the same manner.) This will export your project—any documents and notes you choose to compile—into one document.

Now that you have the basics down, you can explore all the other features Scrivener has to offer. The beauty of Scrivener is that you can experiment with different folder structures, settings, and view modes to find the best workflow for your project. So have fun, make mistakes, and get messy!

Further Reading

Get productivity tips delivered straight to your inbox

We’ll email you 1-3 times per week—and never share your information.

Jamie Irish

Jamie Irish is a freelancer based wherever chai lattes are sold. When not writing, you can find them writing (fiction), writing (music), or writing (poetry).

• Media and editorial

Related articles

How to schedule an email in Gmail

How to add focus time in Google Calendar—and why you should

How to add focus time in Google Calendar—and...

How to manage Discord roles

How to sync Google Calendar with Outlook

Improve your productivity automatically. Use Zapier to get your apps working together.

Documentation #

PDF: novelWriter-2.4.pdf [ Older Versions ]

novelWriter is an open source plain text editor designed for writing novels assembled from individual text documents. It uses a minimal formatting syntax inspired by Markdown, and adds a meta data syntax for comments, synopsis, and cross-referencing. It is designed to be a simple text editor that allows for easy organisation of text and notes, using human readable text files as storage for robustness.

The project storage is suitable for version control software, and also well suited for file synchronisation tools. All text is saved as plain text files, and your project data as standard data formats in XML and JSON. See How Data is Stored for more details.

Any operating system that has Python 3 and the Qt 5 libraries should be able to run novelWriter. It runs fine on Linux, Windows and MacOS, and users have tested it on other platforms as well. See Setup and Installation for more details.

Useful Links

Website: https://novelwriter.io

Documentation: https://docs.novelwriter.io

Public Releases: https://releases.novelwriter.io

Internationalisation: https://crowdin.com/project/novelwriter

Source Code: vkbo/novelWriter

Source Releases: vkbo/novelWriter

Issue Tracker: vkbo/novelWriter#issues

Feature Discussions: vkbo/novelWriter#discussions

PyPi Project: https://pypi.org/project/novelWriter

Social Media: https://fosstodon.org/@novelwriter

Not Just For Coders: Top Version Control Systems For Writers

Your changes have been saved

Email Is sent

Please verify your email address.

You’ve reached your account maximum for followed topics.

Even Though Windows 10 Is Dying, Your Hardware Doesn't Have to Go With It

Why copilot+ pcs are a disaster for average users (for now), 5 ways using linux improved my windows experience.

For years, my computer has been a chaotic jumble of documents with names like "work-document01", "work-document01.1" and so on. I gave them a semblance of organization with timestamped folders. But that was just a false front for my lack of smart organization, or the more complete lack of knowledge about version control systems and how they can be effective for writers.

The mention of version control or revision control makes it seem like something for geeks. You will be surprised to know that version control systems have their place not only in academic writing but in anything that has to do with typing an alphabet on a document.

As writers, we know the word draft . But draft is a mere rough sketch and it doesn't actually take us back in time to the incremental changes we make. With a draft, you would be lost if someone asks you to go back in time and show them the changes you made on a specific date. With version control, you can.

Why Should Writers Use A Version Control System?

Software developers use version control systems like Git as essential tools. Git is a popular and advanced version control system which takes some learning. If you do try to learn Git, you will be introduced to terms like Repository or repo which is the main database for storing all files – current and historical -- related to a project. Branch suggests that someone is creating a separate copy of a file for personal use or testing. Merge or patch denotes the application of changes from one file to another. Revision represents a version of the source code. While Head is the latest revision, Changelog lists all changes made to a file.

These few basic definitions should give you a basic idea behind a version control system and how a writing project can benefit from the organized approach of tracking changes with a VCS.

The benefits are not difficult to understand.

• Track incremental backups and recover: Every document can be backed up automatically and restored at a second's notice.
• Track every change: Every infinitesimal change can be recorded and can be used to revert a file to an earlier state.
• Track writing experiments: Writing experiments can be sandboxed to copies while keeping the main file intact.
• Track co-authoring and collaboration: Teams can work independently on their own files, but merge them into a latest revision – common to the team.
• Track individual contributions: Good VCS systems tag changes with authors who make them.

Once you get into using organized revisions, immediate benefits like overseeing the evolution of a document over time become apparent. The good thing is that you don't have to use specialized tools like Git or Subversion. You can lean on some common tools to implement basic forms of version control that you already might be using as a writer.

Simple Version Control With Dropbox

My friend Bakari mentioned version control with Dropbox in passing when he said it's one of the uses for Dropbox you may not have thought of . Using a cloud storage solution like Dropbox gives you an added dimension as you can access revisions from anywhere. Understanding the Dropbox version of version control is a no-brainer.

Dropbox saves snapshots of every change in your Dropbox folder over the last 30 days. If you are a Pro or Business user, you can avail of the Packrat feature to keep unlimited changes for unlimited time.

• Save your document in the Dropbox folder. As you can see below, I have created a demo folder and a demo file and saved it in my local Dropbox folder that syncs with the cloud.

• Right-click on the local Dropbox folder and browse to the Dropbox website. Another right-click on the specific file shows you the option to check any previous versions of a file.

• Choose Previous Versions and Dropbox will display an online list of the various snapshots Dropbox has taken during the history of the file. Pick a time from which to restore; select the radio button to the left of the file and press the Restore button.

Points Of Note:

• Dropbox allows you to share a file. Any modifications made will be recorded against the name of the person who has made it.
• Dropbox does not have real-time synchronous collaboration features, so the first person's name that saves a revision will be displayed. The other will be displayed as a conflicting copy.
• Dropbox does not automatically save your document.
• Dropbox does not merge changes.

Going To Google Docs

Google Docs brings real-time synchronous editing to documents. Google Docs, Sheets, and Slides have a revision history pane that shows at a glance all changes made to a document by each co-author. To access revision history, follow these steps:

• Go to File – See revision history .

• The Revision history panel opens on the right with detailed timestamps and author name.

• Collaborative edits will be displayed like this:

• Changes made by specific collaborators are color coded in the body of the document in the color matched against the individual in the revision history pane.
• Click on Restore this revision to display a version from a particular time.
• Click the X in the upper right of the 'Document History' pane to return to the current version of the document.
• Google Docs automatically saves your document.
• Google Docs has a Show more detailed revisions option to display finer revisions.
• Google automatically deletes revisions after 30 days or 100 revisions to conserve space.
• Don't forget, with Google Docs integration with Hangouts, this rudimentary version control becomes more useful.

Manage Versions & Track Changes With Microsoft Word

While MS Word does not have true version control, you can automatically save versions of your file while working on them with the AutoRecover feature. It's more of an emergency feature in case of a crash rather than an explicit way to manage versions. I had shown you how to auto save documents with AutoRecover in MS Word 2007 . The idea remains the same. You will find the AutoRecover setting in MS Word 2010 and 2013 under File – Options – Save . By default, it is turned on.

• To recover a file, go to File – Info .
• Under Versions , choose the file you want to recover according to the timestamp.

• On the yellow bar which appears at the top of the document, click on Compare . Clicking on Restore overwrites any earlier saved versions. Clicking on Compare gives you this review screen:

• The Manage Versions dropdown also helps you recover draft versions or delete all draft versions of a document.

The Track Changes feature in MS Word allows a reviewer to make changes to a document, and Word keeps a track of the changes proposed. Its real value comes up when two or more people are working on a document – let's say a writer and an editor.  It is also an essential tool for co-authoring documents.

Here is a YouTube video which shows Track Changes in action:

That's the closest you can come to a method of versioning with MS Word.

• Implementation of version control in MS Office documents needs the help of add-ins like TortoiseSVN which is a Subversion client for Office.

Draft – Because Nothing Else Cuts It

Nathan Kontny, who is the man behind this writer's tool, calls Draft a better version control system for writing. He felt shortchanged by Google Docs and doesn't like the learning curve of Git. Draft is the version control system for writers which removes the complexity and actually makes collaboration smart. Though, Draft deserves a full review, for the sake of brevity I will stick to its core features.

• It starts with a simple sign-in. The Draft interface is like a minimalist text editor. Simply start writing.

• You can mark changes and save them as drafts. You can have multiple drafts. Changes from one to the next are color coded. You can restore or delete any draft.
• You can compare all your drafts and see how it has changed with time.
• With collaboration, writers work on their version of the document, and the main writer gets to accept or ignore each individual change.

• Import your documents from Dropbox, Evernote, Box, and Google Drive. Changes can be auto-synced back to the cloud services. You can transfer a file via FTP or upload it from your desktop. Image uploads are allowed.
• Draft allows you to leave comments and notes.
• Draft has a Chrome extensio n that works on any turns any text area on the into an editable block.

The full features on Draft are well explained . It definitely is a tool you should have in your arsenal if you are a writer.

If you appreciated the simple elegance of Draft, then it's easy to see how it stands out from any of the other tools. When it comes to version control for a writing task, I personally like to keep things simple…with the focus on writing. Draft ticks the "write" boxes. What about you? Do you use version control consciously? Give it a thought and come back to us with your comments.

Image Credit: Abstract White Masks via Shutterstock

• Writing Tips

I’m a writer blog

Guidelines for writing Poems, Stories and Tales

Writing FAQ

What’s the best version control system for a book writer.

May 27, 2022

Asked by: Brian Cox

What software do most authors use.

Everyone used it. Today, even though there are many other word processors out there, Word is still the most widely used book writing software in the U.S. Millions of people continue to use it for their writing needs. And it’s easy to see why. Word has a lot going for it!

What is the most used version control system?

Git . Without a doubt, Git is the single most popular version control system in use. Not only does Git offer the strongest feature set for developers, but it also has the most reliable workflow and is supported by the most third-party platforms on the market.

Which platform is best for writing a book?

The 10 Best Pieces of Book Writing Software

• Scrivener (Word Processor) …
• Google Docs (Word Processing) …
• Google Sheets OR Microsoft Excel (Spreadsheet) …
• Vellum (Book Formatting/Word Processing) …
• ProWritingAid (Grammar/Spell Check) …
• Publisher Rocket (Book Marketing App) …
• Evernote OR Ulysses OR Bear (Note Taking)

What software do people use for writing books?

The four most popular options are Squibler, Scrivener, Google Docs and Microsoft Word . Squibler is the best book writing software because it’s designed specifically to help writers write books quickly and easily by providing a full suite of features to support any type of writer working on any kind of story.

What software does JK Rowling use?

I use Google Docs myself.

What software does Stephen King use?

Q #2) Which writing software does Stephen King Use? Answer: As mentioned on his website, he uses MS Word for books and the final draft for screenplays.

What are the three types of version control?

The types of VCS are:

• Local Version Control System.
• Centralized Version Control System.
• Distributed Version Control System.

Which is Better Git or SVN?

SVN is better than Git for architecture performance, binary files, and usability . And it may be better for access control and auditability, based on your needs.

What version control does Google use?

Basically, Google has built its own “version control system” for juggling all this code. The system is called Piper , and it runs across the vast online infrastructure Google has built to run all its online services.

Why is Scrivener better than Word?

Pros: Made specifically for writing books. While Microsoft Word gets more and more difficult to use the bigger your document gets, Scrivener gets more and more useful as your document grows. That’s mainly because of its “binder feature,” which is a simple but game-changing advance for word processors .

Is Microsoft Publisher good for writing a book?

Microsoft Publisher is one of the easiest and most powerful tools for the beginning self-publisher . Microsoft Word documents can easily be flowed into a Microsoft Publisher book template. MS Publisher files can be printed for self-binding or uploaded into a publisher-ready format.

Is Scrivener the best writing software?

Scrivener is especially useful if you write in a non-linear fashion , like I do, because Scrivener makes it easy to move chapters around and visualize your novel. It’s also a great way to keep all of your research and notes on a book in once place. Scrivener also helps you to understand and manage narrative patterns.

Do professionals use Scrivener?

Scrivener works best for professional writers who:

Have lots of notes or research associated with their books . Plan to write a lengthy, in-depth series.

Which is better Scrivener or Ulysses?

Both Scrivener and Ulysses can help you with compiling, but Scrivener gives you more control . The user-interface is simple on Ulysses, but it is not as thorough and extensive. Scrivener’s compiling process allows you control over every single detail.

What is the best alternative to Scrivener?

Top 10 Alternatives to Scrivener

• Final Draft.
• Microsoft Word.
• WriterDuet.
• Foxit PDF Editor.

Is Scrivener worth getting?

With that said, the consensus of this Scrivener review is that it’s definitely worth it if you want a more old fashioned editor to work in with a lot of functionality . It is a single, one-time fee for a lifetime of organized and productive writing success.

Which is better Scrivener or final draft?

Final Draft Vs Scrivener: The Final Verdict

Both work with the best screenwriting laptops. Two great options even with the price considered I would have to choose Final Draft over Scrivener . Manily because of the simplicity of the platform and the long history it has with people in the movie industry.

Is there a free alternative to Scrivener?

Other interesting free alternatives to Scrivener are bibisco, yWriter, Zettlr and Quoll Writer . Scrivener is mainly a Novel Authoring Tool but alternatives to it may also be Note-taking Tools or Word Processors.

How much does Scrivener cost?

Admittedly, Scrivener is relatively inexpensive at under $50 for a writing platform that allows you to do everything from outlining, to mind mapping, organizing, detailing, editing, and also allows you to compile manuscripts suited for every major platform available to self-published authors.

How can I use Scrivener for free?

If you don’t have a licence, Scrivener will run in trial mode . The trial is exactly the same as the full version but will stop working after 30 days of use. (If you use it every day, it lasts 30 days; if you use it only two days a week, it lasts fifteen weeks.)

Is Scrivener free for Windows?

Ask most experts what the best novel writing software is, and they’ll usually tell you Scrivener. It’s also a popular tool for organizing research for most writing projects, although it’s not free . While they’re not always as robust, free Scrivener alternatives help you accomplish similar results without any fees.

How long does a Scrivener license last?

How long does a Scrivener license last? A Scrivener license lasts forever , for whatever version you purchase. It may cost to upgrade your Scrivener. However, if you bought a license for Scrivener 1 on Windows after July 2017, you will be able to upgrade for free when Scrivener 3 for Windows comes out in 2021.

What’s the difference between Scrivener and Scrivener 3?

Scrivener 3 Is More Intuitive With a Cleaner User Interface

Simplifying the process of using features such as “Compile,” without sacrificing any of their power. Replacing Project Notes, References, and Favorites with a single “Bookmarks” mode. Refreshing the visual feel of Scrivener to be more modern.

Is Scrivener compatible with Windows 10?

Scrivener is available for iOS, macOS and Windows , so you can spread out on a big screen, sync using Dropbox or transfer with iTunes, and then pluck your book from your pocket and carry on writing on your iPhone.

Can you use Scrivener on a PC?

Yes. To download a trial version of our macOS or Windows versions, visit our Downloads page and click the “Download” button for your platform. If you don’t own a licence, Scrivener will automatically run in trial mode .

Does Scrivener run on Windows 11?

Scrivener is ready for Windows 11 .

Related posts

Draft. Version control for writing

I wanted to show off a preview of what I’ve been working on. It’s a better version control system for writing. I call it Draft.

As a writer, I’ve been very annoyed at my options for version control. Software like iCloud and Google Docs end up saving a lot of arbitrary junk making it very hard to find an old draft that has that certain paragraph I ended up deleting and now want back.

And when I share a Google Doc with someone to help edit it, they overwrite my master copy making it insanely difficult to accept individual changes they’ve made.

A lot of folks try to end up learning Git, which is a popular version control system used by software developers. It really is a great tool if you’re in software development. But even as a developer it’s full of headaches. Writers don’t need all this added complexity and overhead to manage versions of their work.

Draft solves this. Draft is a distraction free editor that auto-saves as you type. But as you go along, you can mark major versions of your work:

When you share your document, any changes your collaborator makes are on their own copy of the document, and you get to accept or ignore each individual change they make. Here’s what that looks like:

Draft will be released to the public very soon.

But I’m gradually sending the sign up link to friends, family and folks that want to give it a good trial right now. I’ve been insanely flattered and motivated by the feedback.

The website is one of the most beautiful I’ve seen in a long time. Bijan

If you’d like to try it out early just add your email to the form below.

Now read this

A friend of mine had an idea for an iPad app to help kids with autism. It seemed like a pretty good idea, but he was in a place many others find themselves in. He didn’t have any money. He didn’t have any resources. And he sure as hell... Continue →

Cookies: We use our own and third-party cookies to improve your experience of our website. Cookies remember your preferences and track site usage. By continuing, you accept their use.

Typewriter. Ring-binder. Scrapbook. Everything you need to craft your first draft.

Get your thoughts onto the page and explore the connections between them.

Join the conversation. Ask a question or just get to know your fellow users.

What we’re working on, interviews with users, and general prolixity.

How to Use Revision Mode to Edit Your Scrivener Projects

Kirk McElhearn  /  22 FEB 2023

Scrivener's revision mode lets you keep track of edits as you work from draft to manuscript.

The first draft of any piece of writing is just that: a draft. It takes revision and editing to shape it into a final work. For some authors, the revision process might not be too extensive, but for others, who rework their draft over and over, the process can be quite complex. While you may simply want to make changes to your project without leaving traces, some authors like to make edits in a way that they can see their changes, and perhaps revert to previous versions.

Scrivener's Revision Mode is designed for these writers. You can have Scrivener automatically change the color of new and deleted texts in your project, and you can use five revision levels to record multiple edit passes. And snapshots, which allow you to keep previous versions of the files in your Binder, let you go back to older versions of your texts if you want to revert your edits.

In this article, I'm going to tell you about these tools that help you get from the first draft to final manuscript.

How Scrivener's revision mode works

Scrivener's revision mode is not like tracked changes in some word processors; it merely changes the color of new text, and allows you to apply strikethrough formatting to existing text that you want to delete, yet leave in the project. Here's a close-up view of some revisions in a project. Three revision modes have been used.

While this looks a bit like change tracking in a word processor, you don't accept or reject changes in a Scrivener project; you merely delete what you don't want to keep, then remove the revision formatting colors when you are finished.

To turn on revision mode, choose Format > Revision Mode, then choose a revision level. You'll see this dialog when you enable this feature.

As you type new text, it appears in the revision mode color. If you want to delete existing text, the delete key removes it; however, you may want to mark text as deleted, yet not remove it from the project, so you can go revert your edits at sometime in the future. To do this, apply strikethrough formatting to the text, you want to mark. Select the text you want to delete and choose Format > Font > Strikethrough, or press Command-Shift-_ (Mac) or Ctrl+/ (Windows). In the first screenshot above, you can see a number of words with strikethrough formatting.

When revision mode is turned on, any unformatted text that you paste into the editor appears in the current revision color. To paste formatted text and have it inherit the revision color, and the current text style in the Editor, use Edit > Paste and Match Style.

You may also want to edit text, then mark it when you've finished, but not retain deleted words or granular edits. To do this, turn off revision mode, make edits to your text, such as to a paragraph, turn on revision mode, select the edited text, and choose Format > Revision Mode > Mark Revised. This applies the current revision color to all the selected text.

Note that when you use multiple revision levels, all new changes inherit the currently selected revision level, so you may have edits in first revision level that are superseded by revision level two edits, unless you scrupulously mark deleted text with strikethrough formatting.

To turn off revision mode, choose Format > Revision Mode > None.

Use snapshots to manage revisions

Revision mode lets you mark new text and deleted text, allowing you to later finalize your project. But at each step of the way, you might want to ensure that you don't lose anything. You can use Scrivener snapshots for this. A snapshot is a copy of a text at a given time, which is saved in your project. You can take snapshots, and compare them to revised versions of any files in your project, but also use them as back ups. To learn how to use snapshots, see Use Snapshots in Scrivener to Save Versions of Your Projects . Comparing an edited version of a text to a snapshot displays text in a way similar to revision mode, so working with snapshots could be another way to revise your projects.

Removing revision marks

After you have reviewed an edit pass, you may wish to remove revision marks. There are two ways to do this. If you wish to remove revision marks from a small section of text, select that text, then choose Format > Revision Mode > Remove Revisions. Note that this will remove the color from any text you have added, and text that you have formatted in strikethrough, but the strikethrough formatting will remain in black. You can remove this by selecting all your text, then choosing Edit > Text Tidying > Delete Struck-Through Text.

Revision mode settings

By default, Scrivener uses these colors for revision modes:

You can change these if you wish in Scrivener's settings. Go to Scrivener > Settings (Mac) or File > Options (Windows), then click Editing in the sidebar, then the Revisions tab. Click any of the colors you wish to change and select a new color.

For more on revision mode, see chapter 18.6 of the Scrivener manual.

If you like to keep track of your edits as you work on revising your work, take advantage of revision mode. It's a great way to see what you've changed, and eventually go back to something you had considered deleting.

Kirk McElhearn is a writer , podcaster , and photographer . He is the author of Take Control of Scrivener , and host of the podcast Write Now with Scrivener .

Working with Notes in Your Scrivener Projects | Literature and Latte

How to use character archetypes in your fiction writing | literature & latte, you may also like to read....

Scrivener provides two ways for you to store notes with your projects.

Use Folders and Texts to Power Up the Scrivener Binder

Take a look at how to get the most out of folders and text documents when organising your projects.

Keep up to date

Sign up for the latest news, writing tips and product announcements. Delivered straight to your inbox.

Stack Exchange Network

Stack Exchange network consists of 183 Q&A communities including Stack Overflow , the largest, most trusted online community for developers to learn, share their knowledge, and build their careers.

Q&A for work

Connect and share knowledge within a single location that is structured and easy to search.

Why use version control systems for writing a paper?

I am following the advice of @Piotr Migdal in Is there an internet Git-like repository for collaboration on a paper? , and I want to ask about version controls: how beneficial are they (specially under LaTeX settings) for writing papers compared to Dropbox and SugarSync ?

I have been using SugarSync for almost a year with no pain. Usually, I create the paper folder and invite other authors to join, so we can see and edit the last version of the paper.

• publications
• collaboration
• version-control

• 2 I use version control for all my code, but not for the manuscripts. I tried it once, but it was too difficult for my collaborators. –  dalloliogm Commented Nov 23, 2012 at 11:42
• 7 Three words for you: three-way merge. Even if one does not use version control, I think that every academic writer should learn how and when to use a 3-way merge tool. It is a life-saver; much more fast and precise than doing the work by hand. –  Federico Poloni Commented Nov 28, 2012 at 20:37
• 2 See also: What are the advantages of using version control (git, CVS etc) in LaTeX documents - TeX.SE . –  Piotr Migdal Commented Feb 22, 2013 at 9:37

7 Answers 7

tl;dr: Version control is harder to set up, but makes it safe to work on the same file, and makes it easy to track history (i.e. previous versions).

Pros and cons of syncing files

Yes, the biggest advantage of things like Dropbox (I use it as well for backuping and synchronizing my files) and SugarSync is their easiness.

They may work for collaboration on files, but:

• they are not meant for two people editing the same file at once (no merge functionalities - so one guy changing a file can overwrite changes made by other guy, even without knowing that),
• did anyone worked on that file I want to work know?
• did anyone added or modified any other files?
• which changes were made?
• can I go to a previous version, the one I sent to my supervisor?

Depending what you do, it may not be an issue. For example, if only one is editing tex file, while others are only reading or uploading figures - it's perfectly fine.

And also, look at my answer on Simplest way to jointly write a manuscript? with a not technically-inclined collaborators.

Version control

Version control systems require some technical skills.

Two the most common version control systems are Git and Mercurial (with the second one being more Windows-friendly and, arguably, easier to start).

Both by standard comes only with command line access, but there are some graphical interfaces as well (I really recommend starting with SourceTree ).

So, if the collaborators are techie, just teach them how to use it. If not - there is a way around.

You can keep track of version control by yourself, without engaging others (I'm doing it just now with 2 collaborators).

Just you start a repository inside folder you share (the examples are with Git):

Now, every time you or your collaborator make some changes (e.g. add some files, correct typos, revise a chapter, ...) you do:

Later, you will be able to go back to this version; and also compare, e.g. the current version of your file with the previous one (by default - by line, here - by words):

• Got 15 minutes and want to learn Git?
• git + LaTeX workflow at StackOverflow
• Writing the PhD thesis: the tools Part I
• Collaborating with LaTeX and git at ShareLaTeX blog - a great and comprehensive tutorial
• What are the advantages of using version control (git, CVS etc) in LaTeX documents - TeX.SE
• https://tex.stackexchange.com/search?q=version+control

And real world example from using diff (it makes my life so much easier :)); commit messages in Polish, but I guess you get the idea:

Otherwise ( a strip from PhD Comics ):

• 6 If two people are editing the same file using DropBox, DropBox created "Conflicted copies" rather than try to merge both changes into the same file, thereby avoiding damaging the file. –  Ben Norris Commented Nov 15, 2012 at 13:36
• 2 If two people are editing the same file using DropBox, DropBox created "Conflicted copies" rather than try to merge both changes into the same file, thereby avoiding damaging the file. How can it tell when that happens? The two conflicting versions could be hours or even days apart. This is impossible to do without analyzing the content carefully (and sometimes even analyzing it). –  Federico Poloni Commented Nov 15, 2012 at 16:34
• 3 @Kaz I'm not a computer scientist and for me it worked. –  Piotr Migdal Commented Nov 15, 2012 at 21:45
• 19 One awesome fringe benefit to using version control for a paper: Suppose your print out a copies of version n of your paper and give them to collaborators for comments. A while later, when you're on version n+10 , some of them get back to you, with their changes. With version control (at least with Git), it's easy to enter their changes against version n and then apply them to your current version. –  Eric Anderson Commented Jan 29, 2013 at 20:33
• 4 I use SmartGit to access Git. It's a lot easier than messing around with the command line, and free for non-commercial use. I found it's automatic connection to BitBucket didn't work correctly though, so you have to cut and paste the link. –  Jack Aidley Commented Feb 3, 2013 at 11:21

I'm not entirely sure how dropbox and sugar sync work, but their main aim is not to monitor change, but to keep files in sync over a multitude of platforms and to provide backup. In addition, a good version control system allows you to keep older versions , but also to comment on the changes explain why they where made. The version control is also guaranteed to keep the chain of change of a tex file even over very long periods of time (say submitting to journal a, getting rejected, submitting to journal b, getting reviews, new version, acceptance: such a cycle could easily be 1.5 years).

Also, in a Version Control System (VCS) you decided when you want to save a version , in dropbox I can imagine that the system makes that decision. Being in control yourself is important, for example to be able to generate a difference file when resubmitting a paper (see also my answer to this question on TeX SE ).

Using a VCS you can also collaborate easily with people . Just create a private repository at bitbucket (supports mercurial and git), arrange for the other authors to have read and/or write access to your tex files in the repository, and they can change the paper or add to it. The VCS will take care of the merging.

I use Mercurial myself for version controlling papers. However, for version controlling a tex file, a VCS might be overkill. I would still recommend Mercurial though.

• 3 For one tex file is is not an overkill - see screenshot from my answer and judge for yourself :). –  Piotr Migdal Commented Nov 15, 2012 at 11:07
• 2 +1 Really good answer! There are two things I miss here, though: 1) it's better to split a big file into smaller ones, this can be easily done in LaTeX. 2) When two people want to work realtime on the same file I recommend to put a multi-editor layer before the VCS. C9 or Google Docs are good examples. –  Alba Mendez Commented Nov 15, 2012 at 14:14
• 2 I had to create an account to this Stack Exchange site as well just to give +1 to this answer. :) The nice part about Bitbucket is that there also exists a nice Android client for the site, allowing you to monitor changes to your repositories from anywhere (provided you've got an Android smartphone). VCSs in general are great because they save the author information for all the files in them on a per row basis. Tex files work well with VCSs because they are plain text files, unlike, say, Word documents, where you'd need to use Word's internal versioning features. –  ZeroOne Commented Nov 15, 2012 at 14:39
• 3 @jmendeth for an academic paper I would not split up in subfiles, for a report or book I would. –  Paul Hiemstra Commented Nov 15, 2012 at 14:42
• @PaulHiemstra of course, I wouldn't neither for a paper. But I was speaking in general. :) –  Alba Mendez Commented Nov 15, 2012 at 14:51

Given the praise received by version control systems in the existing answers, I’ll play the devil’s advocate here for a second and underline what I think is a very important point: it strongly depends on what your co-authors are comfortable with .

I use version control for most of the projects I do on my own, from code to papers. However, you have to realize that not everyone is familiar with this paradigm, and those who are familiar with it may not be familiar with a given piece of software (I myself am a heavy Subversion user, but have never used Git…). This is particularly true of people who don't develop software, as those tools come from the field of software development. So, check out what your co-authors use and what they are willing to learn. The great thing about a simple synchronization solution (such as DropBox) with no version control is that its learning curve is flat : just agree on a few rules (date-stamp all files, add initials, always send an email when you have created a new version). Anyone can understand that in a minute.

Finally, I'll add another remark: the need for tracking revision history in the short term needs not necessarily require that you record the revision history for the posterity. For example, my incremental backup system (Apple’s Time Machine) creates snapshots of my files history every hour for a day, every day for the past month, and so on. This covers some of the need for tracking older versions in the short term.

• 1 +1 for the know your collaborators message, but if you are collaborating with LaTeX (vs say Word) users as the OM suggests, they are likely to be more open to the idea of VC (I would think) so it is probably worth making the case. –  DQdlM Commented Nov 15, 2012 at 15:06
• 7 You can also move to a solo workflow when working non-VCS-users: you exchange papers via e-mail with your collaborators, and as soon as you receive them you run a git commit --author="..." on your private git repository. Alternatively, you put a git repository in Dropbox, and tell your co-author to just ignore the hidden .git folder. –  Federico Poloni Commented Nov 16, 2012 at 8:00

how beneficial they are (specially under Latex settings) for writing papers compared to dropbox and SugarSync?

I am a long time user of version control systems, in fact everything I have (my $HOME folder) is backed up in a VC.

I tried hard to use various version control systems for writing many (10+) research papers all of them written in LaTeX. My experience with using VCs for writing research papers is however mixed, if not outright negative. Besides the easiness of synchronization with a VC, the main problem is merging the updates. Unlike source code of programs, merging LaTeX is not that straightforward mainly due to line breaking issues. Secondly, even though I have no problem with various VCs, my co-authors (very heterogeneous mix of people) not necessarily have experience with the one I use, or use different one outright, or have no clue about this stuff. Add the quirkiness of setting up passwords, ssh tunnels, installation of client-side software etc. and you see that all in all, using a VC is not a smooth experience (at best).

Recently (3 papers so far), I gave a try to Dropbox and I am pretty pleased with the result. While it does not solve all the issues, it seems to me to solve at least some:

• almost zero set-up, also layman have no problem installing the client
• no explicit sync, everything just works instantly (no svn/git/bzr/... add/remove/move/... command line stuff involved)
• merging issues are about the same as with a version control system - even with a vc in place I always tended to send explicit write lock notifications to co-authors by e-mail, or IM
• dropbox has some rudimentary version control, for my purposes it's pretty sufficient. Writing papers is not about branching, right?
• moreover, no repository setup is necessary. You just share a folder with a selected group of co-authors and that's it. Nobody else can see it. Few clicks, almost zero hassle.

As you see, my advice would be to stay with Dropbox-like solution . For my purposes, at least, it turned out to be the best solution so far.

As a follow-up to comments received: consider also the requirements you have for writing a research paper. Why to use a heavy-lifting solutions, such as a distributed version control, when we are speaking here about 1-10 text files, a handful of images and possibly a repository of data (binary, or text blobs). Do you really need to go through all the hassle with a DVCS for that? Maybe, if your research is rather a special case, most of the time, I guess, not. To me, easiness and accessibility to laymen of solutions such as Dropbox by far outweighs the advanced technological features, such as branching, tagging, etc.

• Can you choose yourself which old versions are saved in dropbox? You would want to for example keep the version you submitted to a journal for creating difference files, exactly that one. –  Paul Hiemstra Commented Nov 15, 2012 at 8:02
• 1 @Paul Hiemstra: I speak about using dropbox solely for the purposes of collaborative writing. Additionally, I always store the text in my own $HOME folder, which as I said, is versioned separately. But to answer the question, upon a milestone (submission, revision 1,2,...) I always create a separate folder and store the milestone version there. After all, it's about the same as e.g., Subversion would do if you create a tag - it's a separate folder in svn anyway... Remember, a paper is a small piece of data (few kB), not a *GB code base. –  walkmanyi Commented Nov 15, 2012 at 8:44
• 5 “merging LaTeX is not that straightforward” – The way to handle line breaks in LaTeX, since code VCS are all line-based, is to have each sentence on a separate logical line. Modern text editors handle this smoothly and it makes the organisation of the document much more logical, and handled gracefully by VCS. — “Writing papers is not about branching, right?” – wrong. In fact, branching perfectly suits trial-and-error work, or work on separate features/sections concurrently. This is perfect for editing papers. –  Konrad Rudolph Commented Nov 15, 2012 at 17:52
• 1 @KonradRudolph: I do not want to start a flame about these issues, still there's one important non-technological point here. I don't know with whom you write papers, but my experience shows that not everybody is technologically skilled like me. Just installing and understanding e.g., git is hard enough for some, not speaking about wrapping their heads around branching. Did you try that one on a professor over 50? How about colleagues from humanities? Good luck with DVCS and branching. I better write a full paper and collaborate via good old e-mail attachments in the meantime. –  walkmanyi Commented Nov 15, 2012 at 20:50
• 1 @walkmanyi, whatever collaborators use is irrelevant, just handle your end of the mess under version control. –  vonbrand Commented Dec 23, 2015 at 1:11

I strongly recommend using version control for writing a paper because my advisers have never been very good at using computers. They often edit the wrong versions of documents and then send them to me. Then I have to figure out what they changed and manually reenter it into my latest version. I work around this problem by keeping track of what version I emailed to them and then comparing what they sent back to me using release tags.

Don't assume the boss will ever use your version control system. He doesn't need to. But it's still extremely useful to use version control! Our papers are prepared in MS Word because that's all that the boss knows how to use, and that's the file format the journal wants. He often forgets to use the "Track Changes" feature, but you can use the "Compare and Merge Documents" under the Tools menu to determine what he edited. (Just "merge" it with the version you emailed, and the resulting document will display the differences using the "Track Changes" highlighting.) I never have to compare timestamps or worry about which file is the latest version, and even when MS Word destroys one of my figures I know that I can easily recover it.

You can keep all of your raw experimental data, post-processing code, figure files, and lab notes under version control, too. Then you can backup the whole repository and be really sure that you'll never lose anything. I apply repository-wide tags to indicate when I do new experiments, which helps to keep the code in synch with the data; this answers the old question about which method was used to generate the figures. ("Was it method A? We last used that six months ago, but it could've been similar method B that we started developing around that time. Maybe we used A.1? Great, we'll have to do it all over again...")

You can use the repository-pushing feature as a type of distributed backup system. I use TortoiseHg (a Mercurial GUI for Windows) to push/pull the repository to a USB flashdrive to carry between my home and work computers and also to a network share as a backup, and I never overwrite the wrong files or make extra copies of the files. By the way, forget about using the branching and merging features -- they don't really make sense for binary files, but it's valuable to know whether they got accidentally changed. Mercurial works quite well, even with huge binary files in vendor-proprietary formats.

Summary: Real world science experiments produce too many files to version manually, and the boss might not be very tech-savvy. Version control fixes these problems, and you'll never again have to sort through filenames with random dates hardcoded in them.

• 2 +1 for real world situation. :) My boss can't use anything else than Word, too. I'm using LaTeX to write my dissertation and still thinking about how to handle this. –  Eekhoorn Commented Nov 29, 2012 at 10:43
• 2 While I use LaTeX, there's no way to get the boss to use it. "Track Changes" in Word is just too important to him. Maybe you can both compromise and use LyX (www.lyx.org). –  user244795 Commented Nov 29, 2012 at 18:05

There are many good points in the other answers, but I'd like to add another one, concerning the time/project management. Although you can do version control with Dropbox, the main strength of Dropbox is that everybody works on the same file(s) at the same time, which makes it fast and always synced, and it's quite good for a "rush", where n people have to work together over a given period of time on a given objective.

However, I'm currently working on 5+ papers at the same time, with different time constraints, different deadlines, and different involvement, and I appreciate to easily have the history of the paper, who committed what/when, and I like to have to commit contributions to a paper. Hence, I know that the version on the main repo is consistent, and I can leave some parts hanging on a local repo without breaking everything, and when I commit, I need to make the effort to understand what has actually changed and what's the interest. In this regard, the fact that you can easily associate a issue tracker to a repo (for instance with BitBucket ) can be also quite helpful (for instance, you can add an issue "cite this other paper", attach the paper, and solve the issue when you commit the paragraph actually citing the paper.

This project management approach might be a bias coming from my programming background, and might be overkill in some cases, but in the end, there is no killer feature from one approach or the other, it's also how comfortable it makes your life.

I do not have experience with what I'm about to suggest, but it might be helpful. Use both ; use both Dropbox and some VCS . How? Well, in the Dropbox folder that you want to share, start a git repository (see @PiotrMigdal answer). As far as I recall you can exclude a directory from being synced in the Dropbox , and you should exclude the .git (hidden-)directory since it is of no interest to your collaborators.

This way, you and you collaborators can easily share the data over Dropbox and you personally can enjoy benefits of real full scale VCS.

However, as always with shared-digital work, one of the most important issues is to set the guidelines - they should be clear to all participants.

• 2 This is a dangerous suggestion. If someone messes with the .git folder, it can be irreversibly damaged. Git has sharing built in and this can be automated Dropbox style. Use this instead. Not this easy, but way more secure. –  Eekhoorn Commented Nov 29, 2012 at 10:41
• @zenbomb: I see the problem. You could exclude the .git directory from the Dropbox sync. –  Dror Commented Nov 30, 2012 at 7:20
• 1 There is a way out - use bare repository on DropBox which is the remote of the actual full repository which is located somewhere on your drive. –  Dror Commented Mar 8, 2013 at 6:28
• 2 Although unrelated to the question, I must mention that this solution is flawed. You cannot exclude a directory on your local Dropbox folder from being synced with the online Dropbox account. It is the other way round which is possible. –  pnp Commented Jul 11, 2014 at 19:47

You must log in to answer this question.

Not the answer you're looking for browse other questions tagged publications writing collaboration software version-control ..

• Featured on Meta
• We spent a sprint addressing your requests — here’s how it went
• Upcoming initiatives on Stack Overflow and across the Stack Exchange network...

Hot Network Questions

• lme4 Inconsistency
• Is there an economic incentive to use p2wsh over p2tr?
• Dagesh on final letter kaf
• Examples of distribution for which first-order condition is not enough for MLE
• Line from Song KÄMPFERHERZ
• How does this switch work on each press?
• Inversion naming conventions
• Why should I meet my advisor even if I have nothing to report?
• Books using the axiomatic method
• Is anything implied by the author using the (Greek) phrase translated "work with your hands" in 1 Thessalonians 4:11?
• Does concentrating on a different spell end a concentration spell?
• Do Christians believe that Jews and Muslims go to hell?
• Was it a custom to offer a dancer that pleased you anything at all? Like in King Herod’s case
• How to maintain dependencies shared among microservices?
• Hölder continuity in time of heat semigroup
• What’s the highest salary the greedy king can arrange for himself?
• common.apex.runtime.impl.ExecutionException: Unrecognized base64 character: [
• Two definitions of antisymmetrization of a tensor?
• Why can't LaTeX (seem to?) Support Arbitrary Text Sizes?
• Hölder continuity in time of heat semigroup for regular initial distribution
• Evil God Challenge: What if an evil god is just trolling humanity and that explains why there's good in the world?
• mirrorlist.centos.org no longer resolve?
• Blender UV map is very small resolution using TexTool addon
• Unsorted Intersection

Version Control and Academic Writing

Academic writing typically requires writing something in drafts. Many drafts. Until recently there have been few ways of elegantly handling this. Often, one would need to title the current draft with the day’s date, then save this draft in a folder (named, e.g., “drafts” or “versions”), and do this every time one sits down to write. This works, in some ways. The data is there. The problem is that you quickly end up with a folder (or desktop’s) worth of files. These filenames have typically ridiculous and increasingly obscure titles (e.g. final-draft-final-revision\final-draft-04-2018.docx). And it is seldom clear, using this method, exactly what one did when, without actually opening a particular file and looking, or trying to remember when (and where) it was that one made the relevant change.

Nowadays, especially if you use some sort of cloud-based word-processor, it’s likely that you have access to various ways of looking at your version history. For example, Google docs has a revision history option (something similar exists for Dropbox , which lets you easily move back and forth among different versions. Revision histories of this kind offer a way to automatically back up one’s writing. This is especially helpful if you’re not the type of person to carefully name each day’s writing with a new time/date stamp and save them all in the appropriate folder. There are also service (as opposed to application) specific ways of tracking changes to a file. At least some of them allow you to compare differences between versions of files. But at least two things are missing. First, there is no straightforward way of seeing what has changed where, and to see this at arbitrary levels of granularity. Second, in order to see what’s changed when, you have to look in the document itself. There is no general log of the changes you’ve made to the file.

Here’s what I have in mind:

Figure 1: Change Log

You see here a series of entries going back over two years, with a description of what I took to be the most important changes at the time. I can then open any one of the those entries and see a more detailed, line by line, description of changes. This is called a “diff”. I can also roll back the version of the file I’m working on to any of these changes. Each “commit” is a snapshot of the relevant files at the time, which I can retrieve at any point.

I think this is a really nice way to track and visualize one’s progress on some piece of writing. This is hard to do with standard word processors and their means of versioning, but very straightforward to do with a more sophisticated kind of version control system . A version control system can manage changes to a file at an extremely fine level of grain–down to a line or character if necessary. While this system was originally adopted by programmers, it can also be very useful in academic writing (or really any writing where multiple drafts are created).

This form of version control pictured above depends on a system called Git . 1 There are lots of tutorials and other resources for using Git. Though Git is often used from the command line there are also some great free graphical interfaces for Git. There are also a lot of helpful discussions online concerning writing while using a version control system like Git.

The basic idea is that, using whatever writing application one likes, one tracks changes to a document, or a whole directory of documents (e.g. adding image files for presentations, or additional parts of a document kept in separate files when writing longer works like a thesis or novel). The changes can be tracked at an arbitrary level of grain–to the sentence, word, or character–and different versions can be easily compared. All of this can be done without generating lots of files with different numbers or date/time stamps. Everything is kept in a database that one can easily interact with using either the command line or some form of graphical interface.

So far, this isn’t necessarily any different from what one can do using Word or Google Docs. One additional benefit of using a version control system is that one can easily label and describe batches of changes (e.g. revisions to a particular section of a paper or chapter) and keep a single record of these changes. Then, if one want to look back at one’s progress, or for a specific change that one made, all one need do is look at the single general document listing the changes. You can even do this in the text editor of your choice (e.g. vim or sublime text)

For example, here’s a sample log of the changes made to a paper I’ve been working on, using a vim plugin called “ gitv ”, which depends on Tim Pope’s fugitive plugin ( SublimeGit is an equally excellent sublime text plugin).

On the left is the git log of changes. On the right is a more detailed description of what changed–what was added, deleted, or moved.

The basic workflow for using Git is as follows. In the directory you’re keeping your project in (you do keep this in a directory and not just on your desktop right?) you need to create a Git repository. This means typing git init on the command line from the directory, or doing so via whatever GUI app you’ve picked. You only have to do this once per writing project. So that’s:

• cd \path\to\repository
• git add filename.file
• write commit message
• write and quit file

Once you’ve got your repository (or “repo”) you need to add files for tracking. Just type git add and the name of the file you’re tracking. Then type git commit . You’ll then type a commit message to go along with the commit–e.g. “first commit”. Write and quit, or press commit in whatever application you’re using. At this point you’ve got a functioning version control system. So your workflow should be something like the following:

• Add/stage changes
• Write commit message and commit

There’s a lot to Git that I can’t cover here. It can be very helpful when experimenting with an idea. It’s also a nice way to think about and track your work over time. One downside of using a system like git is that it doesn’t work well with Microsoft Word or other rich text WYSIWIG text editors. But there are ways around this .

If you like the idea of git, commit messages, and a readable log of changes you’ve made to a file, but don’t want to deal with the more technical aspects of setting up git and using it, there are also great web apps like Penflip , which streamline much of the process.

• You might also look at Mercurial , which is a popular, and perhaps slightly easier to use, alternative to Git. [return]

Kindlepreneur

Book Marketing for Self-Publishing Authors

Home / Book Writing / LivingWriter Review for 2024: Better than Scrivener?

LivingWriter Review for 2024: Better than Scrivener?

LivingWriter is a powerful word processor built to combine the cloud-based convenience of Google Docs, with the book-focused specialization of Scrivener.

And it does a pretty good job of that too.

For convenience, easy of use, and overall design, I give LivingWriter a 4 out of 5.

HOWEVER, there are some significant drawbacks, namely a subscription cost (which Atticus and Scrivener do not have) or an extremely high one-time lifetime cost, and it doesn’t come with formatting capabilities.

Since you will need a good formatting program anyway, I recommend authors go with Atticus instead, since it is a one-time purchase, and is built for both writing AND formatting.

If you want to go more in depth about what I liked and disliked about LivingWriter, read on.

• What LivingWriter is
• Its core features
• Its pros and cons
• Why I recommend Atticus instead

Table of contents

• What is LivingWriter?
• Is there a free version of LivingWriter?
• Very Expensive Lifetime Option
• Custom Templates
• Outline/Chapters/Sub-chapters
• Story Elements
• Story Board
• Online/Offline Support
• Goals and Word Count
• Version Control
• Pros About LivingWriter
• Cons About Living Writer
• Final Verdict: Try Atticus Instead

Disclaimer: Some of the links in this article may be affiliate links. But as always it costs you nothing extra, and every penny goes to the Kindlepreneur coffee fund. Thanks!

LivingWriter is a word processing app that is specifically designed for book writers, whether you're working on a novel or a nonfiction manuscript. 

It's kind of like a combination of two popular writing tools: Google Docs and Scrivener

Firstly, it offers a user-friendly interface that looks a lot like Google Docs. 

But is also has chapter and scene divisions, which resemble Scrivener's organizational structure.

One of the best features of LivingWriter is that it also has a built-in Story Elements section (which we’ll talk about further down), where you can keep track of all your characters, locations, and general notes. This means you can easily keep track of everything you need to know about your story and your characters, all in one place.

What LivingWriter is NOT is a formatting program . Which means you’ll need a separate program for formatting purposes.

We, of course, recommend Atticus as an all-in-one formatting, writing, and collaboration platform. But more on that in a little bit.

How Much Does LivingWriter Cost?

LivingWriter has three pricing options:

• Monthly Subscription : $14.99/month
• Yearly Subscription : $144/yearly (equivalent to $12.00/month)
• One-time Lifetime Fee : $699.00 (you must be registered for a free trial)

There is not a free version of LivingWriter but they do offer a 14-day free trial so you can see if it’s right for you.

But there is little benefit in using the 14-day trial other than just getting to know the software.

One of the biggest downsides of LivingWriter is that the pricing plans are either subscriptions or a ridiculously high lifetime fee of $699. That's nearly 5X the cost of Atticus.

Here at Kindlepreneur, we’re not big fans of subscriptions, because who wants to write their masterpiece in a tool like this, only to lose it when they can no longer pay the subscription?

That’s why both Publisher Rocket and Atticus are designed to be lifetime products, with no subscription fees.

For example, if you buy Atticus today, you’ll get a quality formatting program, but it’s also shaping up to be a powerful word processor like Google Docs and Scrivener combined, with more features coming.

And all of those new features will be available to everyone who has bought it in the past, along with every new feature to come.

Core Unique Features of LivingWriter

Let’s walk through each of the unique features that LivingWriter offers. Many of these features you will find in other programs, but LivingWriter puts them together in a way that is appealing.

One of the first things that caught my attention upon opening living writer was its custom templates.

This allows you to preselect various outline template such as The Hero's Journey , Save the Cat , and even some more obscure options like Derek Murphy's Plot Dot.

They even have some nonfiction options such as a memoir or PhD Thesis template.

Much like Scrivener, LivingWriter has a breakdown of your chapters and scenes, although the structure is slightly different.

LivingWriter starts with outline sections, generated by the templates or you can create them yourself, with chapters and “sub- chapters” below that.

It's essentially the same as what Scrivener does.

One unique feature of LivingWriter is the ability to add “story elements” that act as a type of glossary for your book. This can be breakdowns of your characters, locations, and events within your story.

Sadly, these elements are not terribly complicated, and I would recommend a tool like Campfire for more thorough world building options.

But the story elements can still provide a quick reminder of certain details that you need to have on hand.

LivingWriter does have a convenient way of visualizing your plot with the Story Board option, which brings all of your different outline elements into one board, so you can switch them around and play with your outline much like sticky notes.

This combines some of the better elements of plotting tools like Plottr into LivingWriter, which is a big plus.

While LivingWriter does provide desktop apps for Windows and Mac, this tool is primarily an online platform.

Unlike Scrivener, which is exclusively an offline tool, LivingWriter syncs to cloud, and there doesn't appear to be a good way of keeping things offline permanently.

However, this is nothing new, and most similar platforms that come out these days also require cloud support.

But at least, it does appear that you can write offline for periods of time, as long as you sync it later.

So far, most of the features in LivingWriter are intuitive to figure out, but if you had difficulty finding one feature or another, the amount of documentation is slightly limited.

I have not had a chance to interface with the actual support people behind living writer, and so I have no basis to comment on their quality.

LivingWriter allows you to set goals for specific project, and see how you are progressing towards those goals. However, it does not have a way of tracking daily habits for writing, like Atticus does.

One of the better features of LivingWriter is the ability to have version control, much like Google Docs.

Everything in LivingWriter saves automatically, so if you find you have made some mistakes, and you need to go back to a previous version, there is a way to find those old versions and revert back to them.

Reports of Bugs

At Kindlepreneur, we get a lot of feedback from various authors about a lot of topics, which is why we can safely say that several authors have experienced a lot of bugs with LivingWriter.

One writer in particular told us that LivingWriter frequently tells him that “A newer version exists locally” when it does not. This is a bug caused by the constant savings feature, which can create a lot of errors with version control. This author was told it would be fixed a month ago and it still hasn't (though it may have been by the time you read this).

So it still has a lot of bugs, and while these may clear up over time, you may still want to consider another writing program.

Atticus, like LivingWriter, also saves with each keystroke, but there's no interruption or errors like LivingWriter is experiencing. Plus there's the formatting. If you are using LivingWriter (or Scrivener for that matter), you'll need to invest in a formatting software as well since, while you can format your book when done, its is VERY limited and tedious. 

There are many things to like about LivingWriter, including:

• Custom templates: LivingWriter offers a variety of custom templates, such as The Hero's Journey and Save the Cat, which can help writers structure their story.
• Clean layout: The layout of LivingWriter is clean and easy to navigate, making it simple for writers to organize their work and focus on writing.
• Version control: LivingWriter includes version control, similar to Google Docs, which allows users to easily revert to previous versions of their work if needed.
• Story elements: LivingWriter has a unique feature that allows users to add “story elements” such as characters, locations, and events, which can act as a quick reference for writers as they work on their story.

Overall, LivingWriter is shaping up to be a powerful program, with a lot of helpful features for writers to use in their process.

Despite the good things LivingWriter has going for it, there are several cons, and some of them are pretty major:

• Subscription pricing or very expensive one-time fee : LivingWriter's main plans are subscriptions, which I don’t like, and can even cause you to lose access to your information if your subscription lapses. Their lifetime fee of $699 is wildly expensive – nearly 5X the price of Atticus.
• Bulk editing/formatting a pain: The bulk editing and formatting options in LivingWriter can be a pain to use, making it difficult for users to make large changes to their work quickly. This is especially problematic when I tried importing my manuscripts from elsewhere.
• Limited documentation: LivingWriter's documentation is limited, which may make it difficult for users to find answers to their questions if they encounter any issues.
• Half-baked story elements and goals: While LivingWriter's story elements and goals features are useful, they are not as robust or developed as those offered by other writing tools like Campfire or Atticus, respectively, and may not meet the needs of all writers.
• Reports of bugs: we've heard multiple reports of bugs from writers who have experience using LivingWriter so far.

LivingWriter is an excellent writing program, but it doesn’t format, which means you’ll need a separate formatting program.

The first version of Atticus was built with formatting in mind, but we are currently working to turn it into something similar to LivingWriter as well.

Already, it has superior versions of some of LivingWriters’ features, such as the Goals feature. Atticus has far more customization options, and even allows you to track writing habits across multiple projects.

Atticus is adding new features all the time, and once it makes a little more progress, it will essentially be the same as LivingWriter PLUS a formatting tool.

Plus, Atticus has two big things going for it:

• Lifetime price: With Atticus, you get access to all future updates for a one-time price of $147. No subscription fees. Ever.
• All-in-one software: With Atticus, there’s no need to have a writing program AND a formatting program. You’ve got it all in one platform.

Since Atticus is also a formatting program, which you will need anyway, even if you already use LivingWriter, then you might as well get Atticus anyway!

Plus, there’s no subscription, so there’s no harm in getting it now, even if some of the features you’re waiting for are still a few months out.

Jason Hamilton

When I’m not sipping tea with princesses or lightsaber dueling with little Jedi, I’m a book marketing nut. Having consulted multiple publishing companies and NYT best-selling authors, I created Kindlepreneur to help authors sell more books. I’ve even been called “The Kindlepreneur” by Amazon publicly, and I’m here to help you with your author journey.

Related Reviews

Autocrit review for 2024: read this before purchasing, memberdash review 2024: wordpress membership plugin, learndash review 2024: an in-depth look at a wordpress lms, sell more books on amazon, amazon kindle rankings e-book.

Learn how to rank your Kindle book #1 on Amazon with our collection of time-tested tips and tricks.

Join the community

Join 111,585 other authors who receive weekly emails from us to help them make more money selling books.

Stack Exchange Network

Stack Exchange network consists of 183 Q&A communities including Stack Overflow , the largest, most trusted online community for developers to learn, share their knowledge, and build their careers.

Q&A for work

Connect and share knowledge within a single location that is structured and easy to search.

Do You Use Any Version Controlling Software/Methods As Writers? [closed]

As writers, do you use any version controlling software to track and monitor what you write? For example, if you accidentally deleted or overwritten a paragraph that you'd like to have it back?

Usually what I do is to save multiple copies with incremental numbers, but I find that this isn't a good method because I end up with a folder full of word documents of the same file + changes. It isn't really easy to organise because of it.

(Storyname 1, Storyname 2, Storyname 3, ...)

This isn't necessary a question about programs, but version controlling software used for writing/writers, methods, tricks, ...

• version-control

• 1 Related question in Web Applications: Looking for a general-use cloud-hosted document management webapp –  Goodbye Stack Exchange Commented Nov 20, 2010 at 19:46
• 1 Not really related, because I'm looking for a solution/workflow that writers use when writing. –  JFW Commented Nov 21, 2010 at 4:39
• 11 It helps a lot if you write plain text, rather than a word processor format. I figure if I've got the text down, I can do whatever else I like later. –  David Thornley Commented Nov 23, 2010 at 4:01
• 5 Bear in mind that, due to how writers.se was formed, it will be heavily biased towards programmers and other software people who want to write at first. –  David Thornley Commented Dec 12, 2010 at 17:06
• 3 Google Docs, for one, does automatic revision history. –  Wayne Werner Commented Jul 7, 2011 at 18:50

21 Answers 21

I am a programmer in real life, so using a version control software was a no-brainer for me. I write stuff in plain text, with each chapters in a separate text file.

I use Subversion on them, with TortoiseSVN on Windows, and also use a Dropbox for backing up my repository.

This way I have my changes versioned, I can comment the changes I commit, and if my hard drive decides to die, I can be back really quick.

• 1 Funny, I use the same thing. Though hosting wise I use VisualSVN. It's easy to setup on windows, you can view it with a browser and it's ready for use on the network. Combine that with TortoiseSVN you can write anywhere in the house with little to no setup. –  Fox Cutter Commented Nov 20, 2010 at 20:03
• 2 isn't Visual SVN a plugin for Visual Studio? –  Axarydax Commented Nov 20, 2010 at 23:05
• 4 I think he means VisualSVN Server, which is a pre-configured Apache Web Server with the SVN Module and a nice MMC-GUI to manage it - it's basically a 2-click-Installation and works with any SVN Client, not just the VisualSVN VS Plugin. –  Michael Stum Commented Nov 21, 2010 at 19:40
• 1 Yep, this is exactly like I do. I use unfuddle for my hosting, so that all of my WIPs are saved offsite. –  JSBձոգչ Commented Nov 22, 2010 at 15:41
• 1 This also works if the software you use for writing saves its text and data in anything close to plain text. For example, yWriter uses XML for metadata and plain text RTF for text, which means standard version control software works really well with it. –  Martin Sojka Commented Aug 1, 2012 at 12:50

You should really just grab and try any version control software presented on the market. This soft is not really more than controlling text files, and text files is what we do.

I use Mercurial and I am very happy about it. It's easy to use for writing alone, as Mercurial tracks all your changes through local repository, and easy to use when collaborating, because it is a distributed version control system . There is also good Mercurial user interface for Windows presented.

But I warn you that file merging is not available, or will be hardly possible, when you're using some kind of text processors (Word i.e). This is problem of all version control systems.

• I do have to point out that merging is not really the fault of the "word processor" as such, just of the existing word processors which do not support (external) version control in any way, shape or form (hmm, I wonder if Word works with TFS... not that I'd use or recommend TFS for that) –  Jürgen A. Erhard Commented Dec 20, 2010 at 20:16
• The only way I've found to get meaningful diff and merge is to write the text source myself, whether that's some XML flavor, HTML, LaTeX, or whatever. Sure, modern tools (and even Word :-) ) have a notion of exporting as XML, but each export will be its own thing with fresh line wrap and stuff, so if you rewrote one sentence the whole paragraph will probably show as a "something changed here" blob, which isn't very helpful. I write all my source in a text editor that won't try to "prettify" or format/export for me, and I can merge and review diffs easily. –  Monica Cellio Commented Jan 30, 2012 at 18:17
• +1 for Mercurial, also new Word .docx files are XML, so merging might be possible (I don't know, I use LaTeX). –  dtldarek Commented Jan 20, 2013 at 9:13
• I also use mercurial, it is amazingly awesome software. I push my repo to a copy on google drive. I also use libreoffice and save in the .fodt format which is a flat XML file, which allows mercurial to properly do diff magic on it. Before that I was using HTML. As for Docx unless something was changed recently, they are still compressed files and not happily diffable. –  Evil Spork Commented Feb 6, 2013 at 11:34

I use git . There are a number of popular GUIs for it, though I tend to prefer the command line.

My backup service of preference is Rsync.net because they are reliable, fairly priced, support (and encourage) you to encrypt your stuff and not give them the keys, and really care about their users' privacy.

• 3 Git works excellently with Latex. In particular, the git diff --word-diff command lets you see changes word-for-word. I recently used Git+Latex for a group presentation, and it worked very well. –  naught101 Commented Jul 12, 2012 at 1:09

I use Google Docs revision history.

True version control systems like SVN and GIT are too complex, requiring knowledge of the command line, and are really designed for collaborative teams, working on dozens of different files, all at the same time. They're overkill for writers.

I use Microsoft Word for writing, and every time I save Google Cloud Connect uploads my revision to Google Docs. I get backup and revision history for free.

If you don't use Microsoft Word try SyncDocs . SyncDocs works like Dropbox, creating a folder that is synced automatically to Google Docs. It also saves revision history.

• They are hardly "too complex" get something like TortoiseHG/SVN/Git to give you a nice GUI. For mercurial, create repo, commit every time you save. not really difficult at the basics, and for anything more complex, just a quick google search can give you the command you need to say revert to a previous revision. –  Evil Spork Commented Feb 6, 2013 at 11:36
• Although I agree with @EvilSpork that Git works well when you're using it simply, when things go wrong (like having conflicting files) or when you try to collaborate with someone else (and you want to merge their pull request), you get thrown into command-line hell rather quickly. –  Seanny123 Commented Oct 16, 2013 at 4:31

Flashbake is a command line interface for a git repository that had some potential but I think it never really took off. It works in the background and is designed to record ambient data as well like the weather at your physical location and the music playing on your computer at the time you are writing.

It is the brainchild of Cory Doctorow and was intended not really as source control but more as an archival tool that future historians could dig through since personal diaries and the like are no longer prevalent.

It's an intriguing idea and it would be cool if something like this became the standard for working writers.

Fossil because it's light weight and easy to backup by just copying the database file to a new location.

• 1 Of course, any DVCS can be easily copied around. And I'd generally avoid calling a VCS with builtin issue tracker, wiki, and webserver "light weight". –  Xiong Chiamiov Commented Feb 4, 2011 at 21:43
• Fossil executable is a single 5mb file that has everything needed. Git is ~650mb and approaching 6,000 files and and 725 folders. (Numbers for Windows). A fossil repository is also one single file. Git is thousands, albeit in a single easy to copy folder. Fossil's web UI features are entirely optional, but as easy to use as GitHub if you want them. This qualifies as light weight on all dimensions I can think of relative to the other choices in the field. –  matt wilkie Commented Nov 27, 2020 at 18:00

I use Celtx as my main writing tool and have subscribes to their Celtx Studio which gives version control.

It's not exactly great because you have to be connected to the internet all the time (there is no "Work locally and sync when you have internet again") and it's slow if you add tons of graphics/media to the file (because everytime you save the entire file gets uploaded), but it's there.

For some other stuff I'm using git and a private GitHub repository because I work as a software developer and just use whatever tools I know and somehow make them fit.

• I am new to Celtx and one of the first things I did was try to put a Celtx project file under SVN version control. It was being treated like a binary file which was not what I had hoped for. Do you know if its possible to have granular version control without having to pay a cloud subscription fee? –  JW. Commented Jul 9, 2012 at 18:58
• @JW Not really. At one point I actually started writing my own Version Control system for Celtx, but in the meantime I switched to Scrivener and haven't followed it through. –  Michael Stum Commented Jul 9, 2012 at 21:20
• I'm just looking at the Scrivener web site now. They seem to have a nice ethos. Thanks. –  JW. Commented Jul 10, 2012 at 7:45

Try Scrivener for this. You're able to make "snapshots" of a piece of work before you make any drastic changes. As well, Scrivener makes backups for you and auto saves while you are writing. Not having to use multiple programs for version control is nice.

• Can you add a link here, so people can get to this software quickly. –  tylerharms Commented Dec 19, 2012 at 20:47
• 1 @tylerharms Scrivener is available at literatureandlatte.com –  Lauren-Clear-Monica-Ipsum Commented Feb 8, 2013 at 21:29
• I have Scrivener set to keep all backups, which is not the default. –  Eric J. Commented Feb 9, 2016 at 22:10

I'm a writer, not a coder, and I started with this same exact question. I started using Git and it works perfectly, though it was definitely took some time to learn. It's cool because Git is popular and there's GitHub and lots of people are into it.

That said, I understand that Mercurial is just as good or better, and much easier to use with "saner" more intuitive commands.

I'm still using Git since that's what I started with, but I spent too much time learning it and it's not better than Mercurial. If I had it to do over again, I would use Mercurial with Atlassian's SourceTree to graphically view and check in changes to drafts as I made them.

It's cool to do some writing, then have SourceTree show you all the additions and edits you made. Then checking in the changes gives you a sense of accomplishment because you can see the progress you made that day. :-)

• 1 You know that Atlassian's Bitbucket works with git also, don't you? That's what I use –  Psicofrenia Commented Jun 29, 2013 at 20:07
• Yes! That's where I have my origin repositories. –  incandescentman Commented Jun 30, 2013 at 0:24

I use Apache Subversion (merely for Android & web development, not exactly content writing) - either self-hosted or on client's Beanstalk or private GitHub accounts.

Just wanted to recommend my favorite clients; both of them are commercial, but affordable and definitely worth the money: Syntevo SmartSVN & SmartGit .

SmartGit supports SVN partially - but only a basic set of commands. The downside might be that one can only compare plain-text files 1:1; on any other files one can just see them something has changed.

With one file per chapter and some script which merges the plain-text chapters into one single file - with chapter-headings and page-numbers, maybe.

I wouldn't recommend TortoiseSVN - but that's probably just a personal thing - any VCS-client which got a full implementation of the command-set should do the job.

I use Subversion and Git as sort of a front end to Subversion.

Using version control has saved my ass several times. I definitely recommend it.

One advantage is that it becomes easy to work on a piece of writing on several different computers.

I do all my writing in text files rather than Word or Pages or Scrivener or anything like that. Version control and plain text go hand-in-hand. However, you can use non-text formats with version control if you prefer.

I use Mercurial (see Daniel's answer for a link). I do my (little, atm) writing in pure text files (with my trusty Emacs ;-D), but in a self-designed (and ill-designed at that, for the moment) "novel" format. That way I have pure text with almost no (currently at least) formatting (which is recommended, according to this very site ;-)) but can generate TeX (or other formats, later) when needed.

If I'm writing something in a plaintext format, like LaTeX or HTML, I'll generally use version control. For example, when I wrote my undergraduate thesis (in LaTeX) I used Mercurial.

For stuff written in a word processor, I generally don't. I do keep backups (using Apple's Time Machine software) so I can jump back in time to any day. And if I start another draft or a major revision, I'll manually make a copy. For minor revisions, I'll use my word processing software's change-tracking functionality.

I've used CVS, SVN, mercurial and git. All work just fine (well, maybe not CVS), but Git has one feature that's particularly handy -- the concept of a staging area.

If you're working on something longer, say a novel, the staging area is really nice. Say you make some edits to chapter 1, some others to chapter 7. With other version controls if you commit your changes it's all one commit. That might be fine for some people, but I really like the ability to commit separately. That way if I want to keep my changes to chapter 1, but roll back the changes to chapter 7, it's easy to do that.

Here's a quick overview: http://whygitisbetterthanx.com/#the-staging-area

• Mercurial has Mercurial Queues , which can be used as a staging area, among other things. –  Faheem Mitha Commented Aug 5, 2011 at 21:04

In a version control system you can perform such things as diff s to basically get a view showing changes from one version to another. You can also create branches, merge branches, and so on. Depending on where you host and what you use, you could also have comments at certain lines (all the way to the extent of discussions). This is usually outside the realm of the source version control, and usually in the webview.

The advantages go beyond single user use. You could for example have a proof read copy and do a diff to check what the person changed. Similarly you could coordinate work with other people responsible for certain aspects of how your writing is suppose to look, proof reading, editing, and so forth, and all this with out going though a iterative time consuming "pass me the last copy" process.

I personally recommend something like git for the simple reason that unlike subversion you can work completely locally anywhere, anytime ie. if it's not too clear, with out Internet, or any server.

It goes with out saying, people tend to find it hard to explain (and the ones I've had to were from a technical background no less). This is particularly true when it comes to the command line tools, but GUIs fair no better. One very key problem is junk getting uploaded, I suggest if you're going to use this as a collaborative system you make sure to set some very clear rules, as seeing unnecessary junk files in the repositories is infuriating.

I've got a couple of things I've done or tried over the years:

1.) When starting my edits or writing for the day, I make a copy of the word doc using the date in the filename. That way, I have a new copy each day and can fairly easily go back to a previous version on a day-by-day basis. This sounds like what you're trying to get away from, but it works for me.

2.) When releasing in eBook format, I version each "release" with a version similar to a software product (I'm a software engineer by day). A "release" consists of the word doc, a pdf (for my web site, Scribd, etc.), an ePub (for B&N), the cover png (for CreateSpace), and the CreateSpace version. All of these files go into a separate folder. Backups are done to Carbonite.

I track the release in a spreadsheet, mostly so I know which retailers have which version. It can get very confusing, very fast if you don't keep some sort of record.

I've entertained the idea of using SVN (source control), but haven't yet had to go to that extreme. I wouldn't recommend SVN for the novice, though. It's easy to get tangled up with it; hours will be wasted trying to make it right.

Microsoft Word (and OpenOffice.org, at least) supports versioning - I don't recall exactly how to go about using it, but in older versions, at least, it seems you just select the 'Versions' option from the file menu.

You can compare different versions with essentially a pretty diff, leave comments, etc.

• 2 MS Word does support versioning, but it has kinda clunky UI and all versions are saved right into the single .doc file - so your short story can have the size of megabytes. –  Lukas Stejskal Commented Jul 11, 2012 at 8:29
• And crash, losing all your work. Not a happy event. –  Joe McMahon Commented Jul 1, 2015 at 5:16
• Well, that's why you save often! That being said, I now write everything in vim and track it with git. But that's not necessarily the thing for everyone. :) –  Xiong Chiamiov Commented Jul 9, 2015 at 19:34

I script Python by day and write by night, and personally I find version control more distracting than helpful. I get so diverted tinkering with it, I end up forgetting about the book itself.

I find the easiest scheme to just increment chapters. A hypothetical chapter 1 becomes chapter 1.2 with a new edited version for example. They alphabetically self-organize in the folder stack that way, and make it easy and clear to scroll to whatever one. When that view, hence view of what I'm doing, gets confusing to my eye I know the story is too; and find that a handy pneumonic.

Well done VC setups are invariably more complex then that, and ironically by their nature will hide growing mess of an author's sprawling story by conveniently compartmentalizing and organizing everything for him. Dangerous dependence for a new writer, I think.

But of course, to each their own! Good luck!

As I'm a programmer I do, as I'm used to it and version control is made for tracking revisions of text, so it is working pretty good with writings.

Pros using version control:

• backup is easier, as I once created backup for my repositories I simply put everything that I want to keep under version control
• I can see and go back to older versions of my writing
• I have a log of my writing activity and can use that for planning
• I can test different paths to go through the story and which one pans out best

I personally use bazaar, but which modern version-control you use is more a matter of taste.

• Related (on "why"): writers.stackexchange.com/q/10440/1993 –  Monica Cellio Commented Jun 22, 2015 at 19:46

If you are using a Mac, one thing that many people miss is that there is built-in system versioning that is available in any app that supports it.

For example, if you are writing in Pages, you can go File ▶ Revert ▶ Browse all Versions to essentially go back in time to previous versions of your document. It works somewhat like how Time Machine works for all files. And it is available on many different built-in and 3rd party apps.

Of course you can also use Time Machine to browse back in time within a folder that contains your chapters or other writing documents.

But it is definitely work exploring learning to write in Markdown (which takes all of an hour) and then that basically makes you a programmer, and you can use programming tools. I write in BBEdit because it gives me the feeling of a long empty page and the writing I make there can be easily machine-converted into any kind of format for publishing. BBEdit has Git and Subversion support.

I use The Novel Factory (as you might expect) which allows me to have tabs for up to three drafts, plus 'blocking'. I also occasionally save a new version of my entire novel file in case I want to go back to something earlier.

I think that if you have too many copies, then, after a while, the overhead of searching for something gets too high. And probably, when you finally go back and find it, you'll discover it wasn't actually the work of genius you remember!

Perhaps that's just me.

Not the answer you're looking for? Browse other questions tagged software version-control or ask your own question .

• Featured on Meta
• Upcoming initiatives on Stack Overflow and across the Stack Exchange network...
• We spent a sprint addressing your requests — here’s how it went

Hot Network Questions

• Can you always extend an isometry of a subset of a Hilbert Space to the whole space?
• Why is a game's minor update on Steam (e.g., New World) ~15 GB to download?
• Is "conversational" used correctly in this context?
• Did Tolkien give his son explicit permission to publish all that unfinished material?
• Why is pressure in the outermost layer of a star lower than at its center?
• Can you arrange 25 whole numbers (not necessarily all different) so that the sum of any three successive terms is even but the sum of all 25 is odd?
• exploded pie chart, circumscribing arc, and text labels
• Remove duplicates in file (without sorting!) leaving the _last_ of the occurences
• How to handle a missing author on an ECCV paper submission after the deadline?
• What’s the highest salary the greedy king can arrange for himself?
• How soon should you apply and unapply the sustain pedal after markings?
• Is it possible to arrange the free n-minoes of orders 2, 3, 4 and 5 into a rectangle?
• I want to leave my current job during probation but I don't want to tell the next interviewer I am currently working
• Phantom points in QGIS do not dissapear
• How many steps are needed to turn one "a" into at least 100,000 "a"s using only the three functions of "select all", "copy" and "paste"?
• Was it a custom to offer a dancer that pleased you anything at all? Like in King Herod’s case
• Why does the Trump immunity decision further delay the trial?
• Why are my star jasmine flowers turning brown
• How far back in time have historians estimated the rate of economic growth and the economic power of various empires?
• Old animated film with flying creatures born from a pod
• Sitting on a desk or at a desk? What's the diffrence?
• Does the Ogre-Faced Spider regenerate part of its eyes daily?
• common.apex.runtime.impl.ExecutionException: Unrecognized base64 character: [
• What's the point of Dream Chaser?

Arcus Education Portal

Data Education for the CHOP Researcher

• reproducible research
• reproducibility
• literate statistical programming

Version control your writing

If you’ve spent much time in reproducible science circles, you’ve probably heard folks talking about how valuable it is to version control your code.

If you’re new to the idea of version control, start with our introduction to version control using git and then come back here to read about applying it to your writing. There’s also a great guide to getting started with git on GitHub , including tons of interactive lessons to let you practice what you learn. If you already have some git experience but need a refresher, check out the git cheatsheet (available in many languages).

In my experience, though, the more surprising super power of version control for researchers is its application to writing! You can apply version control to any plain text file — .txt, .md, .r, .rmd, .csv, and many more.

Version control saves the day!

Allow me to walk you through a few common writing headaches, and show how version control comes to the rescue.

I need to re-work this presentation for a new audience

If you write your presentations as markdown slide decks (which are plain text, and therefore version control-able), then you can create a branch for each new version of the talk you want to create!

For example, maybe you have a great set of slides that you wrote for clinicians and medical researchers explaining how to get started with R. You’re invited to lead an intro to R workshop at a conference, but you know the audience will be much more general. Most of the presentation will work as-is, but you know there are a few slides you’ll want to edit to make the content more relevant. Start a new branch in your repo, and edit the presentation file to your heart’s content — your original version will still be waiting for you, untouched, on the main branch when you come back to it. You can have as many different versions as you like, and still only have one file showing up in the folder, so it never gets cluttered.

If someone else wants to adapt your material for their own presentation, they can fork your repo ! Organizing your material in a repository also may help you remember to include things like a license , citation , and README for your project, all of which make sharing (and getting credit for!) your work much easier.

I’ve spent the last month revising a draft according to my advisor’s feedback, and now she’s saying we should undo all of that and go back to the original framing!

Unfortunately, version control won’t help you navigate the social minefield of incorporating (or dismissing) feedback on your writing. But at least it can take some of the pain out of the logistics!

With version control, you’ll take snapshots (called “commits”) of the work as you make each edit. These can capture changes as fine or coarse as you like, but generally with writing I recommend committing whenever you’re done (for now) editing a particular section and before you move to the next — you’ll end up with commit messages that hopefully make sense to you later, like “add Oliviera 2016 cites to intro” or “take out second set of descriptives in methods”.

In this scenario, all you do is click to review the file’s history and scroll back until you see the beginning of the edits your advisor now wants to roll back. You can now work on your file from this earlier point (but you won’t lose the edits, either — if she changes her mind again, you can still recover all that work).

I spilled orange juice on my laptop and lost all my files

Version control can’t help you here unless you’re also backing up your writing files to somewhere other than your computer, but one of the great things about git is that it makes it very easy to back everything up to GitHub. When you set your project up as a git repo, it’s just one tiny step to connect it to an online GitHub repo and then you have a seamless back-up system in place that preserves not just the current version of each file (as you would get from something like Dropbox), but it’s entire edit history.

If you need to switch machines, or even if you just have multiple computers you like to work on, all you need is a quick pull from the GitHub repo and all your local files will be up to date.

Okay, I’m convinced! What should I keep in mind when I version control my writing?

Stick to text.

The biggest change for most people when they decide to use git for their writing is that they need to write in plain text files only. Version control doesn’t work well for MS Office files (Word, PowerPoint, etc.), pdf, images, videos, etc.

However, I think you’ll be pleasantly surprised to learn just how much you can create with plain text files! Markdown (and, by extension, R-Markdown) is a plain text format you can use to generate an enormous variety of documents, including properly formatted journal articles, slide decks (including PowerPoint), Word documents, pdfs, websites, entire books, and almost anything else you can think of.

For more details on what you can do with Markdown, check out our post on getting more from R-Markdown .

When you’re using git for your writing, the main document(s) you edit will be plain text, like Markdown, and you’ll periodically render them to final output documents in whatever format(s) you need when you’re ready to share with a colleague or if you just want to review the final layout yourself. You don’t bother version controlling that output document, though, and you don’t make edits there — everything of importance happens in your plain text files where you can record the commit history.

Break up big documents

Because you’re already adding a step at the end to turn your plain text into your final output format, many people find they like making that last step not only apply the formatting, but combine several smaller files together. This is a trivial bit to add to the rendering step, but it can help make your commit history a lot easier to navigate.

Let’s say you’re writing a journal article. You could write it all as one Markdown document, or you could save several different files, each for a different section of the paper (e.g. intro.md, methods.md, results.md, conclusions.md). Because they’re separate files, they each get their own version history, which makes it easier for you to browse back through the changes.

If you want a deeper dive into how to think about R-Markdown documents in a project, check out Emily Riederer’s blog post on R-Markdown driven development . Note that the focus of that post is on code-heavy R-Markdown, so if you’re thinking about writing mostly text with little or no code, you may find Emily’s post less relevant.

Keep in mind, though, that your primary audience for your commit history is likely Future You — if you prefer to look at a single history of commits to one big file rather than separate histories for each section, then you should probably not break it up! Do what is most useful for you.

Build good commit habits

Your version control history will only be as valuable to you as your commits, so it’s worth putting a little thought into how to gift Future You with a lovely, informative, easy-to-navigate commit history.

If you haven’t already, read How to Write a Good Commit Message , a short blog post that has become a standard reference in the field.

In addition to the excellent advice in that post, you can do yourself a favor by finishing each writing task and committing before moving on to the next (that’s probably a good habit to build anyway). So, for example, if you get a set of a dozen suggested revisions back from a reviewer, maybe consider each revision one commit — make just the changes for that revision, commit it with an informative message, then move on to the next. This helps you avoid commit messages like “Add cites to intro, move descriptives to front of methods, rework opening para of conclusion” or worse “Edits and tweaks throughout.”

Take advantage of shortcuts

The biggest shortcut for most writers offered by switching to writing in Markdown is that there are tools to handle citations for you. Finally, you can forever say goodbye to writing out your own works cited lists! You just put in pandoc citation syntax for your citations throughout your writing, and when you render the final output document, you can set it up to automatically format all of those inline citations correctly according to whatever style you need, and automatically generate a complete works cited list for you at the end.

Learn more about how to use citations in Markdown and much more in our post on getting more from R-Markdown .

Another powerful advantage of writing in plain text files is that it lets you combine writing and analysis code together in a single file. That means you can have plots, tables, and statistical summaries generated automatically from your analysis right at the point where you want them in your writing — no more copy-pasting output! This is called literate statistical programming, and it’s a game changer. To get started, check out our post on why to use literate statistical programming .

Like this article? Click "Like" to let us know. Like

Get the Reddit app

Ask questions about programming.

Potentially off topic, but does anybody know if writers use Git or version control in general for writing novels?

Just a random thought I had. Seems like it would be a great tool for that.

Combining real-time collaboration with version control for writers.

• Karissa Rae McKelvey
• Scott Jenson
• Eileen Wagner
• Blaine Cook
• Martin Kleppmann

Collaboration features of existing software do not sufficiently meet the needs of professional non-fiction writers. Real-time collaboration in cloud applications like Google Docs can create stress when writers feel watched by their co-authors, and file-based collaboration can introduce difficulty with versioning and merging edits from different co-authors. Further, in environments where accuracy is crucial, like newsrooms, existing tools make reviewing changes unnecessarily difficult.

In the Upwelling project we have built an experimental editor that aims to satisfy the needs of professional writers and editors. It allows co-authors to collaborate in real time when they wish to, but it also supports work on private drafts that can be shared and merged only when their authors are ready. By combining elements of real-time collaboration with ideas from version control systems, Upwelling supports writers in maintaining their creative privacy and editors in ensuring accurate results.

We welcome your feedback: @inkandswitch or [email protected] .

Problems with existing collaboration tools

Professional non-fiction writing often requires several people – authors, editors, and reviewers – to work together in order to produce a finished document. For example, several journalists and editors may contribute to a news article, a group of scientists may collaborate on a research paper, and in business or government the members of a team may jointly write a proposal, report, or documentation. In all of these cases, it is important for the contributors to ensure that the final document is of a high quality, correct, and consistent in both content and style.

Most writers today use two categories of tools: traditional file-based desktop software, such as Microsoft Word, and real-time collaborative cloud software, such as Google Docs. In order to better understand professional workflows for these tools, we interviewed writers and editors working in a wide variety of environments. Several common themes emerged from these interviews:

• The goal is to bring together ideas from multiple collaborators into a single document, such as a news article or a chapter of a book.
• Writers often prefer to initially ideate in private and share the result with their collaborators later, when they are ready.
• Important documents often have a lead author or editor responsible for reviewing all changes before publication. Sometimes there are multiple lead authors. Depending on the setting this might be a formal review process or an informal arrangement.
• Common user interfaces for reviewing changes suffer from readability and usability problems.

The “fishbowl effect” of real-time collaboration

Real-time collaboration allows each user to see their collaborators’ cursor positions and edits as they type, keystroke by keystroke. This has become a standard feature of applications including Google Docs, Figma, the web version of Microsoft Office 365, and Apple Keynote. The widespread adoption of real-time collaboration speaks to the fact that it is a valuable feature. However, we found that our interviewees also had significant reservations about real-time collaboration.

Several writers we talked to wanted a tool that would allow them to work in private, with no other collaborators reading their work in progress. Intermediate drafts aren’t always suitable to share, even with collaborators, and feedback on those drafts can be unwelcome or even embarrassing. In addition, some writers are troubled by the idea that their senior co-workers and management may be monitoring them – an unintended negative side effect of real-time collaboration.

“Writers don’t want first drafts visible to the editor.” — Journalist

Real-time collaboration becomes even more intrusive when others not only watch what a writer is typing but even start editing or commenting on the writer’s work before it is complete. Some of our interviewees reported asking collaborators to close the document and not make edits or comments while they were working. Others reported copying and pasting the entire document into a new file, working there in private, and then pasting the edited text back into the original editor window when finished.

“If you don’t want the editor or writer to see what you’re doing until you’re done, sometimes you make a copy of the doc and work in the copy, then paste it back (otherwise you have 17 canonical documents and people are editing the wrong thing).” — Newspaper Editor

Other writers reported putting their device into offline (airplane) mode to prevent their edits being shared while they worked.

The AutoSave toggle in Microsoft 365 allows real-time collaboration to be enabled and disabled. Google Docs provides an offline mode for working without an internet connection.

We use the term “fishbowl effect” to refer to this downside of real-time collaboration: a writer’s feeling of being watched or interrupted in their workflow by collaborators. Real-time collaboration can be beneficial for lightweight writing tasks (like meeting notes) or when collaborators are working together live (e.g., during a video call). However, our interviews highlighted that many writers prefer working in a private space during phases of individual, creative work.

Versioning in file-based collaboration

Traditional desktop word processors, which edit files on the local file system, do not suffer from the fishbowl effect. They work well for people writing alone, but have the downside of requiring manual version management when collaborating with others. Writers must send a copy of their file to each collaborator (e.g., by email), and when several collaborators independently edit their copies, somebody must manually compare and merge the resulting file versions.

“In the magazine article we wrote, it got to the point where we eventually created our own version history. After a round of comments, we duplicate the document, save v1, and create v2.” — Academic Researcher

File names generated during the writing of an academic paper with multiple rounds of revisions and iterations.

Teams often use file-naming conventions to keep track of these versions. In fact, file names can serve as a rudimentary system for version control. A document named Temporal Paper.docx might evolve into Temporal Paper - Final - PLOS Revisions v3.docx over time. Some teams may use version control systems, such as Git, but such systems are designed for software development and are poorly adapted for working with prose: by default they use a line-based comparison, and they cannot merge file formats that are not plain text. Although file comparison tools for Microsoft Word documents and other binary file formats exist, merging several collaborators’ edits often remains a tedious and error-prone process of manually copying and pasting.

Another problem with file-based collaboration is that unless collaborators remember to explicitly inform each other what they are doing, writers have no awareness of in-progress changes that other writers are making. If two writers edit the same section of a document, the result may be many conflicting edits that could have been avoided through coordination.

“My preferred workflow for Word would be to pass it around one by one—a linear order, rather than having two people working simultaneously.” — Educational Writer

To avoid manually merging documents, some writers use a sequential workflow, sending a file to their collaborator and waiting for the document to be returned to them before making any further changes. This workflow produces a linear version history and eliminates the need to merge versions of the document. However, it also slows down the collaborative writing process, preventing writers from making any changes to a document until they receive an updated version from someone else.

The need for editorial review

Another theme that emerged from our interviews is the need for collaborators to review each other’s contributions to a document. However, review processes differ significantly from team to team. Sometimes several co-authors mutually review each other’s work; sometimes a document has a single lead author who takes responsibility for the overall cohesion and style.

In journalism, very strict review processes are sometimes used: once an editor has read a draft article, writers are no longer allowed to modify it and any further updates require explicit review and sign-off from the editor. Some publications, such as The New York Times , have even developed their own in-house collaboration software, customized to their editorial workflow.

Even though review processes vary between teams, the goal is the same: giving all collaborators the confidence that the final document is accurate, consistent, and complete. Software can support this goal by making it easy to review every change that has been made to the document.

“There can be hundreds of comments, and you can’t search them. If something changed in the doc, we bold it.” — Editor

Visualizing changes to a document

Reviewers benefit from seeing how a document has changed without having to re-read the entire document. Editors have two tools that are typically used for visually highlighting modifications: Microsoft Word’s Track Changes (or Suggestion Mode in Google Docs), and comparison tools that visualize the differences between two specified versions of a document.

Both change tracking and version comparison typically render deleted text in a strikethrough font and inserted text in color (with a different color used for each collaborator). With Track Changes, each edit is additionally highlighted in a sidebar alongside buttons for accepting and rejecting the edit. Comments can also be attached to spans of text to facilitate discussion among the co-authors; those, too, appear in the sidebar.

Several of our interviewees found this user interface problematic. A common complaint was that a heavily edited text becomes difficult to read, because the mixture of struck-out text fragments and multiple colors lead to a visually overwhelming result that obscures the final text.

When many small changes are made to a document, the change tracking view becomes difficult to read.

“I hate Track Changes! I’m dyslexic. I find reading Track Changes to be nearly impossible. If someone has heavily edited, I have to accept all of them and read it.” — Fiction Writer

Another problem is that the person making the changes needs to remember to enable change tracking or suggestion mode before making any edits. Moreover, in the Google Docs implementation of Suggestion Mode, an edit becomes indistinguishable from other text once it is accepted. If one reviewer accepts or rejects a change, any subsequent reviewers cannot use the suggested changes feature to find out what has changed in the document.

Some of those problems can be avoided by comparing two versions of a document instead of tracking changes. However, current word processors do not have a way of attaching comments to a particular text passage within such a comparison view, making it difficult to have a discussion about a change within the document itself. In software development, it is common for developers to break down a large code change into smaller, self-contained updates called commits in order to facilitate code review; word processors, however, do not have a comparable way of grouping together related changes in a manner that communicates their intent and purpose.

Upwelling design goals

In the design of Upwelling we aim to address the problems with existing writing software that were uncovered in our interviews. In particular, we explore the trade-off between real-time collaboration (suffering from the fishbowl effect) and private work (which risks merge conflicts) by providing tools that enable deliberate collaboration and help users navigate conflicts. Moreover, we explore how we can make it easier for collaborators to review each other’s changes, which helps them stay up to date as the document evolves and gives them confidence in the quality of the final document.

As we are interested in the social process of writing, Upwelling is designed for multi-author collaboration, not for individual writing. We aim to support the creation of carefully written formal documents (such as official reports or research papers), not casual writing (such as messages between friends or shopping lists). We also assume a model in which the collaborators trust each other (unlike, say, negotiations between conflicting parties drafting a legal document).

Supporting divergence and convergence

To avoid the fishbowl effect, it is sometimes necessary for a collaborator to work in a private version of the document. This may be because they are trying out a new idea or accumulating edits that they want to share as a batch, or simply because they are offline. We call this effect – some changes made in one document version but not another – divergence .

After diverging, documents must once again converge, bringing together edits from different drafts to a final result. When collaborators make contradictory changes, however, convergence can result in conflicts. Some of these conflicts are apparent from the textual modifications: for example, two writers independently changing the same word into two different alternatives. We call such types of conflict syntactic . Syntactic conflicts are often possible to detect technically, such as when one user edits a sentence that another deletes, or when two users replace the same word.

Conflicts are not always apparent from the textual structure of the document; sometimes changes to different parts of a document can lead to a contradictory result. Human review is required to detect and resolve such conflicts.

Unfortunately, not all conflicts are so obvious: sometimes writers might make changes to different parts of a document that are individually correct but which produce a contradictory result when combined. For example, one author may edit a document to make a terminology change throughout, while their co-author adds a new section that uses the old terminology on a separate draft. When those edits are merged, the result is a document in which the use of terms is inconsistent.

When conflicts exist not in the structure of the text but rather in its meaning, we call this kind of conflict semantic to differentiate it from the syntactic conflicts described above. Perhaps, in the future, AI tools will be advanced enough to automatically detect (and perhaps even resolve) such semantic conflicts. For now, however, we prefer to emphasize the social workflows of writing in Upwelling, providing tools to help users navigate such conflicts rather than trying to solve them automatically.

Borrowing ideas from software development

Software developers collaborating on a code base are already intimately familiar with the process of divergence and convergence: for example, when using Git, a software developer typically edits source files locally on their machine, groups their changes into meaningful chunks called commits , and then shares them in the form of a pull request or merge request . Different team members may work independently on different branches , and only merge each branch once it is ready, often after having undergone a code review process.

By default, software developers generally do not use real-time collaboration in the style of Google Docs because it is unproductive for one programmer to suffer another programmer’s half-finished, buggy code while simultaneously working on their own, unrelated, half-finished code. The exception is when two developers are closely collaborating in real time on the same task (“ pair programming ”), in person or via a video call, or when one developer is giving a live explanation of some code. For such situations, tools such as Visual Studio Live Share enable software developers to opt in to real-time collaboration where appropriate.

Visual Studio Live Share for real-time code reviews and interactive education , Microsoft (2018).

This freedom to choose between offline private work and real-time interactive collaboration, depending on the situation, is something that we believe is also important for writers. Moreover, the process of code review, through which the quality of the final product is improved and team members are kept up to speed on changes being made, also has a direct analog in writing. Version control tools facilitate these workflows by providing branching, merging, comparison, and visualization of the editing history.

Unfortunately, version control tools like Git, which are designed for software development, do not suit the needs of writers. Git cannot compare or merge files from WYSIWYG editors such as Microsoft Word, and although it is possible to train writers in Markdown or other plain-text formats, Markdown files in a Git repository lack important features from Google Docs and Word, such as associating comments and discussion threads with text passages. The command line interface is unfamiliar to most people who are not software developers, and graphical user interfaces for Git are cluttered with complex concepts such as commit hashes and visualizations of non-linear branching and merging histories.

The “railroad track” model, as used in GitX for visualizing the branching and merging history of a Git repository.

Upwelling aims to synthesize some of the benefits of existing writing tools with some of the benefits of formal versioning systems while avoiding the shortcomings of both.

The human in the loop

As discussed previously , it is important in many writing projects that one or more collaborators review every change made in order to ensure the quality of the final document and uncover any semantic conflicts.

In software development, where code review is also an important part of the workflow of many projects, the version control tooling helps facilitate this review process: developers can structure their changes into commits , such that related changes are grouped into the same commit, and unrelated changes are placed in separate commits. A commit message helps provide a rationale for the changes (outside of the code itself), a branch name helps identify the commits, and GitHub’s “pull request” feature allows collaborators to have a discussion about the commits before and after they are merged.

In existing tools for writing prose, the review functionality is much more rudimentary. Google Docs’s Suggested Changes and Microsoft Word’s Track Changes treat every consecutive sequence of character insertions or deletions as a separate suggestion, and do not provide any way of grouping related edits into anything resembling a commit. When many small edits are made, the document’s margin quickly becomes cluttered, rendering discussion on suggested changes difficult to follow.

In Google Docs, every consecutive sequence of modified characters becomes a separate change suggestion, occupying space in the sidebar. When many small edits are made, the user interface becomes difficult to manage.

When a writer wants to diverge by working on their own version of a document, Upwelling allows them to choose the granularity of the changes before merging back into the main version. Like in a Git commit, the writer can collect related changes into a unit that can be reviewed efficiently, even if those changes modify many parts of the document. For example, a terminology change that requires replacing all occurrences of one word with a different word can be reviewed and merged as a unit.

We found in our interviews that the details of review processes differ significantly from one writing team to another. Upwelling therefore does not impose any one particular review process, but rather provides a variety of tools writers can use to review and integrate their collaborators’ changes.

Reducing the risk of conflicts

While working on separate versions of a document has the benefit of giving writers space to experiment in private and avoid the fishbowl effect, it has the downside that prolonged periods of divergence lead to a greater risk of conflicts. Upwelling aims to help collaborators navigate this trade-off.

In Upwelling, it is possible to group and merge related changes as a unit. Similarly, unrelated changes can be reviewed and merged independently without the risk of introducing conflicts or losing work. This combination encourages writers to limit divergence and merge changes into the main document as soon as they are ready.

An author might use one draft to replace all instances of one term with another, allowing a collaborator to quickly review the change while concurrently carrying on discussions about a more involved rewrite of a particular section of the text. Splitting the two tasks into separate drafts makes it easier to review and merge (or discard) each one as soon as it is ready.

Upwelling also minimizes conflicts through a semi-private mode of writing. A writer can share in-progress changes without merging them into the final document. This offers less privacy than working completely offline but allows each writer to always have a sense of what their co-authors are working on.

Upwelling implementation

Upwelling is a collaborative text editor that follows the design goals listed above. It is a research prototype, not a finished product, but we hope that it will inspire other collaborative writing products.

Upwelling introduces a few new concepts. Instead of writers editing the document directly, a document is built out of layers , and every edit occurs within one. Layers are titled, have one or more authors, and support comments for discussion or review. A layer can be edited until it is merged and joins the stack . The stack contains the complete editing history of the document.

Layers and drafts

An Upwelling document is always edited within a layer. We call unmerged layers “drafts”. To change the document, a writer creates a draft and gives it a title to describe their intent to other contributors. Within the draft, a writer can edit the document as they would in any other text editor: by inserting or deleting text, by changing its formatting (e.g., from roman to italic), or by leaving comments.

Every edit to an Upwelling layer is tracked, and a contributor can always switch between viewing the document in its final state or visualizing their changes for easier review. This differs from existing products, which require a writer to enable change tracking before making a revision.

An Upwelling document can have multiple drafts at the same time, all of which are separate from each other: edits made in one draft do not appear in other drafts. As such, a writer who needs a private space can create a new draft and work there in solitude. But writers don’t have to work individually: a writer who wants to can also share their drafts to collaborate in real time.

Sharing Drafts

Every draft has a title; this can be used to explain its purpose and intent, such as “Reworking the introduction” or “Copyedit Section 2.” A draft therefore serves a similar purpose to a commit or a branch in Git: it allows related changes to be grouped together, which helps collaborators understand what changes are being made and why. The existence of a shared draft titled “Reworking the introduction” also helps communicate to co-authors that they should avoid making changes to the introduction in other drafts, since they are likely to conflict.

In Upwelling, users can see all drafts accessible to them, including their name, creator, and the number of changes that have been made to them (to indicate how far the draft has diverged from the underlying document), via a drop-down menu. This is similar to GitHub pull requests, which show the number of added and removed lines. If several writers edit a draft, each contributor’s changes are highlighted in a different color.

Draft Dropdown

Reviewing and merging drafts.

A draft collects a meaningful set of changes made by an author. Unlike change suggestions in Google Docs, where every individual edit results in a separate suggestion and potentially triggers an email notification, an Upwelling draft allows the author to share a set of related edits only when they are ready to do so.

A reviewer can leave comments on a draft to give feedback or request changes, but they can also simply edit a draft directly. Because Upwelling tracks all changes automatically, identifying those contributions is straightforward.

Reviewing changes

Once the authors of a draft are satisfied with it and want to incorporate it into the main document, they can merge it into the document’s stack of layers. Once the layer is merged, we no longer call it a “draft”. A merged layer can no longer be modified; to make any further edits, the writers must create a new draft.

Upwelling does not enforce any particular permissions or process around merging drafts: any collaborator is allowed to merge any draft. Some teams have formal review processes that may require, for example, an editor to sign off on every change. Rather than rigidly encoding such processes in our software, we believe that it is better to implement such processes as social conventions around how the software is used. For example, a team may agree that from a certain point onward, only the editor is allowed to merge drafts, even if in principle the software allows anybody to do so.

Our interviews suggested that even in professional environments, policy is governed by social rather than technical enforcement. Upwelling makes this strategy even more robust: because a full history of the changes to a document, with full attribution, is always preserved, writers and editors should always be able to determine who made a change and recover from any mistakes.

Merging Drafts

Looking at the stack.

A merged layer is placed on the top of the stack. The stack captures the full editing history of the document, starting from the moment it was created as an empty document, and each merged layer represents a batch of changes relative to the previous (lower) layer. The stack thus enables a writer or editor to review the work their colleagues have done over various periods of time.

To navigate this history, a user can select a reference layer using a drop-down menu. Selecting a layer causes changes after that point to highlight similarly to the “Show Changes” view within a single draft. This allows a collaborator to get caught up on changes merged by other editors, or just to get a sense of what parts of the document have been edited most recently and by whom.

Comparing Versions

Upwelling highlights insertions with a light background color and marks deletions with the traditional proofreaders’ symbol for a deletion, “➰”. To reduce the visual noise of showing changes in the text, we avoid rendering deleted text in a strikethrough font, instead allowing the reviewer to see the deleted text by hovering the mouse over the ➰ symbol.

Rejecting changes

The primary means for accepting or rejecting changes in Upwelling is per-draft: an editor can choose to merge or, alternatively, delete a whole draft at once. Within a draft, an editor can also make fine-grained adjustments — inserting or deleting additional text at will.

We feel this approach is preferable to the span-by-span review acceptance (or rejection) process presented in existing products, because it allows for the grouping of related changes. By using several independent drafts, a copyeditor could separate uncontroversial changes, such as comma usage or capitalization corrections, from more invasive changes.

Although drafts replace the need to accept changes one by one, there are still some circumstances where it could be useful to reject changes within a draft, or even to revert an entire draft after merging it. We chose not to implement either of these features, but we describe a design for them below.

It is common for an editor to either disagree with a suggested change (and reject it) or to ask for further clarification or additional changes when reviewing a draft. We recommend supporting this with an inline interface as depicted below.

Reject Button

Similarly, it may be useful to provide a mechanism to retroactively remove a layer from a document’s history. Conceptually, we think the right approach would not be to rewrite history but rather to add a mechanism that creates a new draft which applies new edits that reverse the layer in question.

Managing conflicts as drafts merge

As explained above , drafts are independent from each other in Upwelling: edits in one draft do not appear in other drafts. With this in mind, what should happen to existing drafts when a different draft is merged onto the stack?

One strategy would be to leave the other drafts unchanged. This approach has the advantage that a draft represents a stable version of the document, with no changes from other collaborators unexpectedly appearing. However, we believe that this approach increases the risk of conflicts, because authors of one draft may remain unaware of the changes that have been merged. Moreover, allowing a new draft to be based on an older draft in the stack leads to version histories that are complex to visualize and hard to understand, such as the “railroad track” diagrams depicted earlier .

Upwelling takes a different approach: all drafts float on top of the stack of merged layers; when one draft is merged, all other drafts are updated to include the changes in the merged layer. Using a Git analogy, every time a branch is merged into main, all other branches are automatically rebased on top of the latest main.

Floating Drafts

Users who are viewing a draft receive a notification when a draft is merged onto the stack. To avoid disrupting the writer’s flow, the currently viewed draft is not immediately updated: the writer can delay the update of their draft until a time when it is convenient for them. We believe that this design strikes a compromise between giving writers space to work without interruptions while also keeping them apprised of what their collaborators are doing.

Updating a Draft

Floating drafts help surface conflicts to collaborators so that they can be addressed. When different drafts contain syntactically or semantically conflicting edits, and the first of those drafts is merged onto the stack, the collaborators working on the unmerged drafts are notified. They can then use the change highlighting feature to see the changes in the merged layer and the changes in their current draft at the same time. A quick review of these changes allows the writer to determine whether there are any conflicts. (As discussed previously , detecting semantic conflicts requires a human review, as it cannot easily be automated.)

Because changes from merged layers are automatically incorporated into all existing drafts, a draft reflects the document that would be produced if that draft were to be merged now. There are therefore no surprises when the draft is merged, because any conflicts that may arise will already have surfaced. In settings where every word counts, an editor can carefully review every draft before it is merged and verify that the final document precisely matches what they have reviewed. This would not be the case if drafts did not float on top of the stack.

How Upwelling works

The Upwelling text editor is a web application that works offline . Upwelling is written in Typescript and React , and communicates with a NodeJS server that stores data and connects users during live collaboration sessions. It uses ProseMirror as its underlying text editor.

Upwelling’s collaboration features are built on top of the Automerge CRDT, which we use to track every single edit made to a document. To support asynchronous collaboration, the stack and any active drafts are combined into a single tarball (along with an additional Automerge document containing some metadata) then uploaded to the server. Real-time collaboration uses the sync protocol built into Automerge.

Upwelling is built on an experimental fork of Automerge which added some additional features not available on the stable release. The fork adds support for rich text formatting and attributing edits to individual authors. These features will be available in a more stable form in future Automerge releases.

Upwelling also works without a server. Writers can export a document as a file by appending ?download to their URL, or import a document by dragging into the application. This capability is useful for debugging, but could also support alternative clients or data distribution strategies such as emailing revisions.

We iterated through a wide variety of different designs during the Upwelling project. Each of them taught us something. Sometimes things that seemed promising in a paper mock-up were unusable in practice. Other times, ideas that came from our engineers inspired new features in the design. Our findings here are drawn from that process, and from our experience working with Upwelling within our group.

Always-on change tracking puts writers in control of their experience

Google Docs conflates change tracking with review, requiring writers to manually choose to track changes. Because tracking changes is visually distracting, this forces writers to select between a comfortable writing experience or supporting thorough review. Upwelling, in contrast, records the full history of the document and lets a writer decide on the fly how much historic detail to surface.

In our interviews, we heard that making detailed edits to a paragraph with change visualization enabled can be distracting and make it difficult to read the final product. In some cases, we suspect that a reviewer may prefer to temporarily disable “Show Changes” in order to allow them to read the document more easily.

Both real-time and asynchronous collaboration are needed

Our user interviews indicated that both real-time collaboration and asynchronous collaboration are useful in professional collaborative writing projects. However, most existing software supports only one of the two modes. Google Docs is real-time–only. Microsoft Word supports both real-time (for files stored in the cloud) and asynchronous collaboration (files stored locally that are shared by email, for example), but a file can only be in one of the two modes, and the modes cannot be mixed.

Git supports asynchronous collaboration only (creating a Git commit for every keystroke would be inefficient and onerous for the user). It is possible to combine Git with a text editor that supports real-time collaboration, such as Visual Studio Live Share . However, as discussed previously , Git and other version control systems have many usability problems around merging and history visualization that make them difficult for writers to adopt.

As we developed Upwelling, we experimented with an asynchronous-only collaboration model but found that while drafts often have a single primary author, those authors often find it useful to be able to share an in-progress draft for initial feedback, or to ask for help with wording or copyediting before merging a draft. The need to combine both real-time and asynchronous collaboration produced the “layers” model: within a draft all changes are automatically merged in real time, but each layer is deliberately merged (presumably after review) onto the stack.

Automatic merging is necessary but not sufficient

When several writers are collaborating in real time on the same draft, the network delay between the writers can lead to concurrent edits that cause their views of the document state to temporarily diverge. When writers are working on different drafts, the document states of those drafts can diverge more substantially. In both cases, algorithms are important for automatically merging those diverged states.

In the case of real-time collaboration, manually merging every keystroke would require an unreasonable amount of effort, so automatic merging is essential. With asynchronous collaboration, the situation is more nuanced, because merges happen less frequently, and greater divergence leads to a greater risk of conflicts. We believe that automatic merging is nevertheless useful in the asynchronous case, because it quickly produces a merged document that can then be reviewed for conflicts.

Upwelling performs automatic merges using a CRDT algorithm , which provides good support for merging both real-time and asynchronous edits. In particular, when a draft is merged onto the stack, the CRDT is used to incorporate the edits from the merged layer into every other draft in progress (which we call rebasing above). This merging process handles syntactic conflicts in a simplistic way: for example, if “white” is changed to “frosty” in one draft and to “soft” in another draft, the merged result is either “frostysoft” or “softfrosty.” This result requires human follow-up to correct, which should be made obvious through review using tools like “Show Changes.”

It is tempting to try to devise more sophisticated merging policies or user interfaces for resolving syntactic conflicts. Unfortunately, since semantic conflicts cannot always be detected, human review of the merged result is necessary in any case. We therefore prioritized a design that makes reviewing changes easy rather than investing in more sophisticated merge behavior.

It’s better to avoid conflicts in the first place

Rather than introducing more sophisticated handling of conflict cases, we believe that it is better to manage the social process of writing in such a way that conflicts are less likely to arise in the first place. Many conflicts can be avoided if the collaborators communicate their intentions to each other beforehand (for example, “I’m working on the introduction today, please don’t touch that section”).

The current design of Upwelling allows editing intentions to be communicated through the naming of drafts. In future work, it would be interesting to explore further UIs for capturing intent: for example, a writer working on a draft might reserve a section of the text so that the software shows a warning message if others attempt to edit the same section in a different draft. Another possibility would be to provide early warning regarding potential conflicts by alerting collaborators if changes to other drafts have affected parts of the document close to the section they’re working on.

Finally, perhaps the most straightforward way of reducing the risk of conflicts is to limit the number of edits made in each draft: we encourage writers to merge drafts before they diverge too far from the existing stack. Smaller drafts are not always better (in the extreme, creating a separate draft for every single keystroke would not make much sense), but keeping drafts fairly small and focused on a single subject, and swiftly merging them onto the stack, helps writers stay apprised of what their collaborators are doing.

Keystrokes should be grouped meaningfully

In Google Docs and Microsoft Word, every sequence of consecutively inserted or deleted characters becomes a suggestion that can be individually accepted or rejected. We believe that this approach is too fine-grained, and Upwelling instead provides drafts as a way of grouping together edits that are related to each other—e.g., a copyediting pass over a particular section of the document. This grouping is particularly useful for collaborators who need to review what has changed and why. Upwelling’s approach mirrors the use of commits in Git and other version control systems.

By allowing several drafts to be in progress at the same time, Upwelling allows unrelated changes to be placed in separate drafts, similarly to multiple branches in a Git repository. Git, however, offers some powerful history rewriting features that Upwelling does not; for example, it is not possible in Upwelling to “cherry-pick” a subset of commits from a branch, to combine (“squash”) several commits into one, or to split one commit into separate commits.

While Git’s history rewriting features make it possible to fine-tune the grouping of edits into commits, we decided that adding similar features to Upwelling would introduce too much complexity and add too little value. In order to make drafts as easy as possible to review, Upwelling does not allow the grouping of edits within a draft to be changed.

When reviewing a draft, if an editor finds that they want to use some but not all of the edits it contains, they can simply edit the draft to change the unwanted edits back to what they were before. We believe that this approach is much simpler to understand than a cherry-picking interface, and is equally effective.

Draft layers should be independent from each other

Early during the design of Upwelling, we experimented with restricting drafts to a single author, corresponding to writing workflows with clear role separations between writers and editors. Single-author drafts make it easier to attribute authorship. However, we found that in this model, if an editor wanted to leave a comment or even just fix a typo in a draft, they would have to create a new draft to contain that edit, and this draft would have to depend on the earlier draft it referenced.

In Git, branches can be dependent on each other: you can have many branches that depend on other branches, not just on the main branch of the repository. Within a branch, commits from different authors can depend on each other. We experimented with “Git-like” dependent drafts in Upwelling and found that it made the model more difficult for users to understand and did not add meaningful value. Moreover, it encouraged the use of long-lived branches, which in turn increases the risk of conflicts.

A key insight of Upwelling is therefore that there should be no dependence between one draft and another, and that each draft should be able to contain edits from several collaborators (with edits automatically tracked so that different writers’ contributions can be highlighted when necessary). This approach enables a familiar real-time collaboration model within a single draft and allows any given draft to be merged onto the stack as soon as it is ready, independent of any other drafts.

Drafts should float on top of the stack

When watching collaborative writers work, we noticed that they spend significant time reviewing changes to a document before calling a particular version the “latest” or “final” draft. We want to preserve this valuable process; we believe it helps editors ensure semantic consistency of the final document. In particular, we want to ensure that if a reviewer reads a draft and then merges that layer onto the stack, the resulting document will be exactly the same as what they just read.

Upwelling achieves this property by having drafts float on top of the latest stack; in other words, when a draft is merged onto the stack, it is also merged into all existing drafts. Any conflicts are therefore surfaced and resolved in the drafts before they are merged onto the stack.

A prerequisite for this behavior to work as expected is that in the moment where a writer merges a draft onto the stack, their copy of the stack is completely up to date. Two collaborators concurrently merging different drafts onto the stack would violate the principle that the reviewed draft is identical to the final document, because the result of the concurrent merges could contain unresolved conflicts. The Upwelling prototype currently does not enforce this rule.

One way of enforcing “one merge at a time” would be to keep track of the latest stack on a server, and to allow writers to merge onto the stack only if approved by the server (writers would still be able to edit drafts while offline; they would only need to be online to merge a draft). Another approach would be to design a custom CRDT that allows merges of drafts to only happen sequentially; if multiple collaborators concurrently tried to merge different drafts, only one would succeed and the others would revert back to draft status.

Future work

We built Upwelling to explore the UX of collaborative writing software. Though you can try the demo now, we do not recommend writing a thesis in it just yet. Still, we think that the concepts and technology from Upwelling can serve as the foundation for full-featured products. Future work might include:

Permissions and sharing

Upwelling uses a fairly simple permissions model: a draft is either completely private to a single writer or it is shared with everyone who can view the greater document. As a convenience for demonstration, individual drafts receive a unique sharing link which can be shared to invite new people to that draft. Anyone with that link can view, edit, and merge the draft in question.

We deliberately did not implement a more complex permissions system because we found that professional collaborators usually trust each other, and therefore Upwelling can rely on social processes and conventions to manage the workflows for a document. For example, if a team has agreed that only the lead author should merge drafts onto the stack, they can abide by that rule without requiring it to be enforced in software.

In future work, it would be interesting to allow for drafts to be shared with only a few co-authors before sharing with the broader team. For collecting feedback from external reviewers, it would be good to be able to generate a link that allows a reviewer to make suggestions and leave comments on a particular draft without being able to see other drafts or merge that draft. This would allow the authors to send a document to several people for feedback at the same time and still keep each reviewer’s comments private from the others.

For some use cases, such as journalism, it might be necessary to enforce more rigorous access controls. For example, free-form editing of an article may be allowed while it is still being drafted, but once an editor has reviewed it, further changes may only be merged with the editor’s approval. In such a scenario, drafts may also need additional attributes, such as a flag to indicate whether it is ready for review yet.

In security-sensitive situations, as when writers are working with sources whose identities they wish to protect, it could be important to elide the history of a document. Because Upwelling currently records and shares the full history of a document, there is no way to excise names or information that may have appeared in earlier drafts. This is a problem caused by keeping too much history, a consequence of changing from a design that keeps much less.

Empowering users to control how much document history they share with their collaborators is an open problem. Solving this will demand both new user interfaces and also new data structures. CRDTs are currently designed to guarantee that users will see the same results from the same inputs. In this case, users will want to see the same results from different inputs.

Viewing multiple drafts at once

The user interface of Upwelling currently only allows users to view one draft at a time, even though the underlying CRDT library does in principle allow several drafts to be viewed at the same time. For example, if several reviewers each leave suggestions and comments in a separate draft, the lead author might want to see all reviewers’ comments at once rather than having to switch between several draft views.

When a writer is viewing a single draft and they make any edit to the document, that edit can be added directly to the draft they are viewing. The problem with viewing multiple drafts at once is that if the writer wishes to make an edit, it can be unclear which draft that edit should be implemented on. For this reason, the document would probably have to be read-only when viewing multiple drafts at the same time.

Interface improvements

Change highlighting.

When reviewing changes (within a draft, or across layers in the stack), change highlighting aims to make it efficient for a reader to understand how a document has changed. We believe that Upwelling’s style of change highlighting provides better readability than the style used in Microsoft Word and Google Docs, which render deleted content as crossed-out text. Instead, Upwelling hides deleted text behind a small marker: the “➰” symbol. This design could be refined in future work by exploring alternative ways of highlighting changes.

Partially reverting changes

In Upwelling it is easy to make small edits to a draft and then to “accept all” changes in that draft by merging the layer. However, in some cases, a reviewer might want to accept only some of the edits in a given draft and not others. We designed a feature for partially reverting the edits within an individual draft but have not yet implemented it in Upwelling. This feature would be worth exploring in more detail.

Attribution and additional context

When highlighting changes, Upwelling currently displays authorship through nicknames and colors. It would be interesting to explore showing additional information about edits (e.g., time, name of the draft, merged by, etc.), especially for teams that require more formal review and approval processes.

Other content types

Upwelling currently only supports text with basic formatting; it does not yet have support for code, images, videos, tables, or other content types that also occur in professional writing. Further work should investigate what kinds of collaborative workflows arise around these types of data, and how to support them.

Supporting different workflows

Our user interviews and the design of Upwelling have focused on professional non-fiction writing. We already understand from our user research and professional experience on the team that fiction writing, in particular, tends to exhibit different editing patterns and team dynamics than non-fiction writing. In future work, we would be interested in understanding these behaviors more deeply and designing user interfaces to support different working styles.

While Upwelling is currently a research prototype, we would like to see these ideas incorporated into existing word processing software. An ideal implementation would offer a file format or exchange protocol that makes it possible for writers to use the writing software of their choice to create documents while offering support for Upwelling features.

Professional writing is ill-served by both a traditional file-based approach and the modern cloud approach to collaboration. Writers and editors across a variety of disciplines perform elaborate work-arounds due to the shortcomings of existing solutions. In particular, writers express a desire for creative privacy and only sharing work when it is ready, and editors need to closely follow the development of a document so that inconsistencies do not creep into the final version.

Upwelling addresses these needs with a new model that unifies real-time and asynchronous collaboration. Instead of treating writing and suggesting changes as separate modes, Upwelling tracks all edits and allows changes to be highlighted retrospectively. To support real-time collaboration, Upwelling tracks changes at the granularity of individual keystrokes, but it also encourages writers to group related edits into sets of changes that can be reviewed efficiently, similarly to commits, branches, and pull requests in Git.

We hope that future collaboration tools for professional writers will incorporate the ideas from the Upwelling research prototype and adapt them to the needs of their audience. As the technological basis for Upwelling (in particular, CRDT libraries that can efficiently track editing history and automatically merge drafts) matures, we believe that Upwelling presents an opportunity to significantly improve the writing workflows of many knowledge workers, including scientists collaborating on research papers, journalists writing articles, and educational writers preparing learning resources.

Thank you to Chris Sun (daiyi) and Peter van Hardenberg, who contributed to the development of Upwelling. Special thanks to Orion Henry, who worked tirelessly on the Rust implementation of Automerge to make Upwelling fast and reliable. Thank you to the Peritext team (Geoffrey Litt and Slim) for conducting interviews that inspired this project, and for their design of Peritext, the rich-text CRDT used in this prototype. Thank you to Todd Matthews, who designed the diagrams, and to all contributors who gave valuable feedback on early drafts of this paper. A special thank-you to all interview participants, who gave their time to inform the design goals.