Help your Spocks and Kirks get along with Git and Markdown
Product managers don’t want to mess with complicated toolchains; they want to get work done in a lightweight tool and share it easily. On the other hand, engineers need source control to ensure that their code and internal documents can be trusted. I recently talked to someone who wanted product management to be able to collaborate on specifications and other documentation that could then be managed in source control.
There are many collaboration tools that give you the comfy WYSIWYG collaborative experience product managers like — Google Drive, for example, or Dropbox Paper — and then there are tools that integrate with source control so that engineering teams can participate easily. If only there were a workflow that could do both!
I have some good news for you.
Now that you’ve started using Markdown, learned how to take notes in Typora, and figured out how Git works, you’re ready to use the Git Centralized Workflow and a WYSIWYG Markdown editor to manage documents across teams. Here are the tools you’ll use:
- Markdown — because it’s easy, because you can do so many things with it, and because it’s a great format for source control. Yes, you can use AsciiDoc or reStructured Text instead if you like.
- Typora — because it gives you a comfy WYSIWYG environment similar to tools you’re already used to. Yes, you can use Sublime or Atom instead if you like.
- Git hosted on GitHub or Bitbucket — because Git is the best source control. Yes, you can use your own repository if you like, or host on another service such as GitLab.
- GitHub Desktop or Sourcetree — because they make it simple to manage all the source control stuff in Git. Yes, you can do all your Git stuff from the command line, if you like.
You can do a lot of complicated things with all these tools, but the goal of this tutorial is to show you a workflow so simple, even the pointiest-haired of your colleagues won’t be fazed by it. The idea is to create a Git workflow and make it feel almost like working in Google Drive. Here’s how we do it:
No branching.
It’s called the Git Centralized Workflow. If you really need branching, go for it, but think about this: in your documentation, specs, requirements docs, and notes, will you ever need to separate work in that way? Probably not. For this workflow, do everything on master.
What your day looks like
With everything set up properly, your workflow is simple:
- Click Pull.
- Work on your files.
- From time to time, click Commit.
- At the end of the day, click Push.
Let’s look at the steps in a little more detail.
When you start in the morning, open Sourcetree or your preferred Git desktop client and click the Pull button. This gets you the latest copies of the files along with changes other people have made.
Open the working folder in Typora. There are a few ways to do this. For example:
- Set Typora up to always open the folders you work in
- In GitHub Desktop, click Open in Typora (after setting your editor in Options)
Typora makes it easy to see all the files and work on them. For extra convenience, set your preferences in Typora to save files automatically. If you set up Typora the way I describe in What if you can’t use Evernote, you will be in good shape.
Whenever you get to a stopping place in your work, create a checkpoint called a commit — basically, a snapshot of your work. Commits make it easier for your collaborators to understand what you’ve done, and they create points in time that you can roll back to if needed.
Here’s how to commit:
- Stage the changes you want to commit — in this workflow, it’s likely to be everything. In Sourcetree, click Stage All. In GitHub Desktop, make sure the checkboxes next to your files are checked.
- Type a short sentence describing the work you did, then click the Commit button.
At the end of the day, or when you are ready for your work to be seen by others, click Push to add it to the central repository.
That’s it!
Getting set up
If you don’t have a Git repository yet, create one at GitHub or BitBucket. Then set up the tools:
- Install Git.
- Install a Git desktop client such as Sourcetree.
- Install a Markdown editor such as Typora.
Once the tools are installed, clone the Git repository to your computer. You can do this from within the desktop client by going to File > Clone. You can find the URL by viewing the repository online in BitBucket or Git.
You’ll be working in the master branch, so all you need to do is make sure your Git desktop client is pointed to the master branch on the remote repository.
In Typora, open the File view (left nav) and navigate to the folder containing your local copy of the repository. For convenience, set your preferences in Typora to open the folder on launch.
Solving problems
The biggest problem you are likely to run into is a merge conflict. This happens when you and someone else have both edited the same part of the same file. In that case, Git needs to know which edit to keep. In a workflow where you are collaborating on documentation and specs, this can be a rare occurrence — but if it happens, it’s not hard to resolve.
The Git desktop client will tell you if you have a conflict.
You will need to view the Markdown directly: in Typora, click View > Source Code Mode. In other Markdown editors, you should already see the Markdown source.
A merge conflict looks like this:
<<<<<<<HEAD
This is the edit you made
=======
This is the edit someone else made
>>>>>>> {big long number}The text between the word HEAD and the equals signs is your edit. The text between the big number and the equals signs is the edit someone else made. All you have to do is replace all of this stuff with the text you want — either your edit, the other person’s edit, or some text that includes both.
Most other problems have to do with forgetting to pull or forgetting to commit. The Git desktop client will let you know.
Maybe we can all just… Git along
With these tools, working directly in Git and Markdown is almost as easy as using a dedicated cloud collaboration tool — but with the added benefits of real source control and integration with engineering workflows.
Update: If you want more information, I actually wrote a book that talks about this (and other Markdown stuff): Markdown Dreams: How to do things with Markdown and Git
Update to the update: I thought Git Doesn’t Have to Be Hard might be an interesting enough topic to write a whole book about it. So I did:
