scott chacon did a nice write-up talking about the workflow he used while writing the second edition of his tech book — on the topic of “git”, which is a distributed revision control system that programmers use to manage code.
> https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272
the pre-publication second edition is available, free, in multiple formats:
> http://git-scm.com/book/en/v2
chacon cofounded github, a tool built on top of git, so he knows his stuff. and github got an investment of $100million a while back, which explains why he can afford to make his book available for free before it is published. between the first and second editions of his book, he became a wealthy man.
and he loved the process of writing the book while using his new workflow.
even if you don’t know exactly what he’s talking about — most of us won’t — it’s impossible not to share the excitement of his newfound empowerment…
consider this:
“Now we had Pull Requests for review and commenting,
Issue milestones for chapter planning,
prose diffs for easier review and spot-checking, and
the Atom text editor for writing and Asciidoc preview.”
and this:
“We could make a branch
for the unit of work we were doing
(normally a chapter)
and start writing and pushing to the GitHub branch.”
and this:
“We opened a Pull Request almost immediately,
usually with a checklist of things
we wanted to complete before merging
so you could tell what the status of each branch was”
and this:
“When a branch ran long, we could
merge the master branch into it to keep it up to date
and make sure that conflicts were never a huge problem
…
Review was done through the Pull Requests”
wow.
this is a tech person being excited! can you tell? this geek was having fun! :+)
and why not? as he said:
“It was an amazing writing environment.”
writing a book is more often described as “birthing a child” than “amazing”. the last time anyone called ms-word “amazing” was back in the last century.
now, like i said, chacon knows git and github. he knows them inside and out, and his expertise is clearly revealed by his nonchalant use of all their jargon.
thus anybody else who has a working knowledge of git(hub) will understand why he said this:
“The workflow we got to use is one that
everyone who has ever written a technical book,
especially with a co-author,
will probably be insanely jealous of.”
this is a tech guy having so much fun his friends will be insanely jealous!
but those people with no understanding of git(hub) will be left in the dark, to marvel at the skills of superiors, like viewers of “dancing with the stars”; that is, we are impressed by what you’re doing; we’d like to do it ourselves, but we have no idea how, so we know we’d end up tripping over ourselves.
because we don’t even know what a “distributed revision control system” is.
and we don’t want to learn, not even for “an amazing writing environment.”
***
at the end of his piece, chacon sums it up by saying “this process is at least the short to medium term future of technical publishing.” and you’ll be inclined to agree with his assessment. or at least not attempt to seriously contradict it. sure, the system is convoluted, but if you are talking about tech publishing… well, the geeks seem to like to embrace a certain amount of masochism, eh?
but he continues: “all of this has very serious and interesting implications for the publishing industry as a whole, which I’ll write about in depth in a future post.” uh-oh. now he wants to have all of us get out on the floor and do the salsa.
i might wanna save chacon the trouble. or at least give him things to ponder.
***
first of all, it’s a bad idea to talk about “the publishing industry as a whole”, because that industry is a group of dinosaurs in the process of going extinct. (in passing, chacon notes his publisher wanted the manuscript in ms-word.)
the future consists of writers using streamlined workflows that enable them to connect directly with the audience of people who will support their work. so if you want to talk about “the publishing industry”, talk about “writers”…
tech-writers are writers, too, of course, but most writers are not techies, and most writers don’t want to have to become techies to get our writing done… writing is difficult enough, by itself; writers want our tools to help us write…
and, in that particular vein, git(hub) doesn’t really look to help us too much.
here’s why:
* git(hub) is too in-your-face for writers
so we can write, we want our tools to get out of the way, not take up our day. coders can play with git(hub), but writers have better ways to procrastinate.
* git(hub) is geared to code, not writing
just exactly what is a “pull request”? or a “rebase”? and who gives a “fork”? our terminology has to do with things like “chapters” and “narrative thrust”.
* git(hub) has a clutter of functionalities
even if we did understand the full range of capabilities offered by git(hub), how do those concepts and functionalities hook into the process of writing?
* git(hub) lacks necessary functionalities
spell-check? can you fix “its” and “it’s”? or the dreaded “now/not” mix-up? got global find-and-replace? limited to selected text? or with step-through?
* git(hub) track-changes is way too ugly
track-changes is vital, yet git(hub)’s version doesn’t display too well for us; and slapping yet another coat of paint on it won’t fix it; the plumbing is bad.
***
i did that outline, and was gonna flesh it out, but i’d say it speaks for itself…
it’s just my opinion anyway. if writers do indeed find git(hub) to be useful, then i’ll happily admit i’m wrong. but i’m pretty sure it ain’t gonna happen.
it’s slightly uncomfortable for me to say it to one of the github cofounders — i feel like the instructor who told me my daughter was too fat for ballet —but github is most assuredly not the future of publishing, let alone writing.
that doesn’t mean github can’t work for writing, if you already know it well. because it can... if you stretch it far enough. and accept a few shortcomings. but if you’re honest, even then you’ll admit there’s an impedance mismatch.
can github be modified, to work for writers? well, yes, it certainly could be… but you would need to hack it considerably, and revamp all the terminology.
and the question then becomes whether it’d be easier to instead build a tool from the ground up, with laser-focus on the specific functionalities needed. i believe that approach would be less work, and more successful, in the end. (and i spent my own time and energy building a system with that approach.)
but, you know, chacon does have a $100million war-chest to work with, so…
***
however…
now, let me be perfectly clear that writers do indeed need a better tool-set…
and one will come, and chacon will probably think that it’s “very similar to” the system he used. but the vast majority of writers would disagree, because that better tool-set will not have nearly the steep learning curve as git(hub). nor will it have all the unneeded functionalities that git(hub) has. but it will have necessary functionalities that git(hub) doesn’t currently offer writers…
that is, the new tool-set will offer the benefits of git(hub), but not the costs.
more to the point, its philosophy and its jargon and its mindset will all be geared specifically to the writing process, so writers will be at home with it.
in other words, the tool-set will have to make the writing flow more easily…
so, in closing, let’s talk about a few things that will do that, just as examples:
* the future is plain-text storage-format
plain-text is the best path for a track-changes system, which writers require.
* the future is light-markup to apply tags
in the near-term, .html is a required output format, so we’ll need .html tags.
* the future is flexible on storage places
writers must be able to access work online or offline, using many machines.
* the future is high-quality multi-outputs
burgeoning form-factors require highest quality on multiple output-formats.
* the future is draft output while writing
work-in-progress output is a great way to proof, and to visualize completion.
* the future is savvy on how outputs look
wysiwig worked for paper. now we need the equivalent for multiple-outputs.
* the future is instant easy collaboration
most writers don’t write with collaborators, but good writers have an editor.
* the future is simple solid track-changes
for quality collaboration, the ability to stet changes is an absolute necessity.
* the future is robust and radical to remix
thanks largely to its use of structured text (strext), the future can do remix.
* the future is simple yet quite powerful
writing tools need to be simple, but they will grow to be very powerful too.
***
again, the outline speaks for itself. or maybe you don’t understand it, now, not every item anyway, but look back again in 5 years, and check how i did…
***
and, finally, for the record, i will note that there are tools like i’ve described that are in the process of being developed this very moment, some of them fairly far along and working quite well. rather than list a selected few now, i’ll instead devote an entire essay doing a review of them at some later time. (however, i couldn’t resist using a screen-shot of one to illustrate this post.)
for now, i will say simple yet powerful systems are on the way, lots of them, so there’s no need for writers to trot off and learn git(hub) yet. maybe ever.
stay tuned for that review!…
-bowerbird
