Being a Git!!

To paraphrase Linus Torvalds, he’s an egotistical bastard and so he always names his software projects after himself. Hence the name Git!
This post is not for coders, hackers or other nefarious creatures who write software for a living. This post is aimed at the common (wo)man in an ordinary old business.
Why would that sort of person be interested in Git? The Git that’s a distributed version control system (DVCS)? The Git that’s written for software development teams, like the one that builds and maintains the Linux kernel?
Let’s look at Git a little bit first (please don’t go away…I’m getting to the point). Git is:

• A file system based version control system. That means it keeps its files in the file system of your computer, accessible to you with all the tools you might normally use to manipulate and work on those files.
• A distributed system. That means that there doesn’t have to be a centralised repository although there can be. It also means that you can keep a copy of the repository on your local machine - desktop or laptop or both - and you can share it with other users without a central repository…or with a central repository or a number of central repositories.
• A version control system. That means it keeps track of every change to every file that is added to Git for the life of the repository.
• Capable of initialising and using remote repositories to enable repositories to be backed up and shared.
• Lightweight, in the sense that it is trivial to install and manage, but deceptively powerful.

Imagine a scenario where you are an executive in a company, you travel a lot and you are currently working on a major rebranding of a product line. You are using an external graphic designer to create the logo and the “look” for the rebranding.
You want to be able to work on the rebranding project - all the documents and supporting materials - on the plane when you are travelling and in your hotel rooms. Meanwhile the designer is working on the logo, the general branding, the templates for the brochures and product information. She needs your feedback regularly. You’ve tried doing this by email and saving files to your local machine. However your boss is very picky, he wants to make sure this is exactly right. That means that you and the designer have been through multiple iterations and you are both losing track of the file names which are starting to look like logo_draft13_pete_v0.23.
This is the sort of situation where Git excels. It is trivially easy[1] to set up a Git project that saves you all the hassle. It would look something like the following picture.

Here’s how it works:

• One of you would set up a local repository and, because of your specific needs, that person would also set up a remote repository[2]. It might be possible to operate in this scenario without a remote repository but it will be simpler with one.
• That person would then add[3] and commit all their relevant files to their local repository.
• That same person would then push their local repository to the remote repository.
• Person two would now clone the remote repository to their local machine.
• Finally person two would add and commit any files that they have that are relevant and that are not yet in the repository. They would then push their local repository to the remote repository. Person one would pull the remote repository. Now both people have all the files in their local repository and all the files are also in the remote repository.

Now the small fly in the ointment is that Git, by design, is a command line tool. Most of us can’t be bothered with tools like that. We are so used to GUI tools that we simply don’t want to work any other way. So we want a setup like this:

Every platform has various Git GUIs available, I use Sourcetree on the Mac but there are lots of choices.
As each person works, they work on the files in their local repository. They add new files to that repository and commit those files. At each commit Git takes a snapshot of the project and gives that snapshot a unique name. You can wind back to any commit at any time. It’s like endless versioning.
When either of you is ready they can push their local changes to the remote repository. This merges those changes into the remote repository. The other person, when next on line, is warned by their GUI tool that they are “behind” the remote repository so they can pull the remote repository to their local repository. That merges those changes in with their work and they can then push their changes back to the remote repository. Then the other person can pull…and so the process goes on[4].
Of course the next thing that happens is that your boss wants to see where the whole project is up to…well they can just clone the remote repository onto their machine and they have all the files to hand. The boss then thinks you need more help, the project’s growing, so he assigns two more members to the team. They just need access to the remote repository, they clone it and they’re ready to go.
This brief run through has barely scratched the surface of how Git can be useful to “non-coders”. For more information start with the following references.
Git homepage
A great Git book freely available on-line.
Github is a hosted Git service with both free and paid plans.
Git is also used as the “back end” for blogs and wikis and a whole range of other tasks. Google around and see what you find.
Oh, did I mention that Git is Free Open Source Software?

---

1. Installing Git is a very simple and quick process, indeed if you have a Mac or a Linux machine it may come already installed, if not it’s the work of 30 minutes. Installing Gitolite (see other footnotes) is the work of maybe an hour, mostly getting keys set up. Anybody who can type in the console and can read instructions can do this from the very good directions available. Once installed setting up a repository takes less than 5 minutes.  ↩
   
2. Remote in this sense means on a server accessible to the internet. Typically this repository would have its access controlled with something simple like Gitolite. Gitolite enforces extremely fine grained access control and requires all traffic to occur over SSH which is a secure link. Alternatively you could use a hosted service like Github.  ↩
   
3. Text formatted like this denotes an actual Git command line command. To add a file called test.txt to Git the command would be entered like this: git add test.txt with add being the key word. You can do it quickly and simply from the command line, or more usually, you can use a GUI tool.  ↩
   
4. Git can diff files between commits to show you what has changed. In general this capability is limited to text files of all sorts. Binary files such as PowerPoint, Word, Illustrator…can’t be diffed. Git knows that they have been changed, but can’t tell you visually what has been changed. Nevertheless Git keeps a version of every change that you have committed.  ↩
   

Formatting Doesn't Matter

Tools like Word and FrameMaker, InDesign...they're great. You can tweak and twiddle with the formatting to your heart's content. You can make the content look just like you want it to, down to the smallest little thing.

But here's the rub: It doesn't matter a damn. The reason you are creating this content is to communicate with others. The people you are trying to communicate with don't give a damn about all the tweaking and twiddling that you've done. They simply want something that's clear and simple to understand. So you spend a very high proportion of your content time fiddling with formatting - for no good reason whatsoever.

Before you come chasing after me and telling me I'm wrong, I know that what I've just said doesn't apply to marketing and advertising material. If you are going to put an ad in a colour magazine, then yes you should tweak it to within an inch of its life.

That kind of content however only accounts for a very small proportion of the content that companies create. By far the largest proportion of the content is what could generally be called "technical documentation". My contention is that formatting - beyond the most basic - only matters to one person: That person is you. It doesn't matter to the consumers of that content. The consumers of that content don't care about all the time that you spend tweaking that content. They only care that the content is clear and simple to understand.

I heard an alarming statistic recently: A company had a documentation process where the engineers wrote the documents in Word and then the writers came along and edited it and tweaked it until it looked right. How long do you think it took to create each page of documentation? Eight hours! Eight long hours.

That company changed to a process where the engineers input the content into an XML editor and then the writers edited it for sense. The content was output to publication through a standardised process. The new documentation approach took 1 hour per page of content.

That is a huge difference. It is a huge saving for any company, particularly when companies report that documentation costs around 6% of revenue.

I think there is a lifecycle with writers. At some point in their career they become obsessed with presentation. They love the tools that deliver that presentation to them. Whole departments become obsessed with presentation, and indeed whole companies can become equally obsessed with the "company look and feel". Fine if you are delivering a web site. Forget it for the rest.

Later writers and companies move beyond the attraction of presentation and begin to realise that most of their content is functional content. Functional content is just that: content with a function. If it fulfils that function and does it well, then that's what you are after.

That's why companies move to DITA, S1000D and other similar standards. Because they realise that they cannot afford to be fulfilling the fantasies of their staff who are obsessed with presentation. Presentation without relative benefit.

That doesn't mean that you cannot deliver presentation using XML standards. It does mean that the design and codification of presentation is a Write Once and Once Only process, just like with content preparation. Then you just run it when you need it.

The worst possible situation is to move to one of the XML documentation approaches and to try and drag your presentation fetishes with you. Then you really are taking it too far!

So for all those people who cannot free themselves from the tyranny of presentation my message is to Just Do It. I promise you'll feel better.