Modern technical writing - Andrew Etter 2016

Use distributed version control
Specifics

All sorts of people, most of them much smarter than me, have extolled the virtues of distributed version control systems (DVCS) like Git and Mercurial over centralized systems. The basics are that DVCS have better performance, allow for offline work, and are superior for concurrent work on the same file. For technical writers, the most important reason to use DVCS is that developers prefer them.

Because version control systems are designed for software development, each and every one of them is overkill for the typical documentation workflow. For example, you'll probably never need git reflog. So why worry about which system you use, when they can all do the job? Because when you select Perforce, Subversion, or CVS, you are basically confessing to potential contributors that you can't be bothered to use modern tools.

Atlassian Bitbucket and Stash are both excellent web-based interfaces for managing remote repositories. GitHub and GitHub Enterprise are also great options. While the default user interface, git-gui, is decent, I prefer Atlassian SourceTree and GitHub Desktop. The terminal is always there if you need advanced functionality. Many people even prefer it for basic, everyday operations.

If you have the opportunity to store your documentation in the same repository as its corresponding product source code, strongly consider doing so. The approach has some real appeal:

· Documentation and code branches stay in sync.

· Developers are more likely to contribute if they don't have to clone a separate repository.

Of course, this approach also has some cons:

· If a repository is large (e.g. 2 GB), checking out the entire repository just to access the 40 KB ./docs directory can dramatically slow down documentation builds.

· Onerous commit hooks and pull request submission policies, designed to keep a code base stable, can make even simple documentation changes a chore.

Wherever you store your documentation, place a file named README.md in the root of the repository (or in ./docs). This Markdown file should include:

· A quick summary of the product being documented

· Instructions on how to build the documentation locally

· Instructions on how to contribute