So, here are our tips on collaborating within a documentation project with Git, all of which have been forged through our own journey of trial, error, and resolution. We try to remove the barriers and encourage any member of the team to contribute to docs, which comes at the price of having to resolve the odd conflict. Last but not least, we believe that owning content doesn’t mean acting as a gatekeeper. These developers are a rare and highly valued species – and you don’t want to put them off by locking files for editing or introducing another process around contribution to docs. There are developers who may want to make minor updates to the docs instead of filing an issue with a tech writer.Taking turns to edit the same file is not an option – and here is where conflict resolution and merge tools come to the rescue. In our case, this involves a dozen different authors and often happens a few days before the release. Such content is the responsibility of the team of IntelliJ IDEA technical writers, and once it’s finalized, an automatic workflow creates issues for the writers responsible for other JetBrains IDEs who then customize and adjust it for their products. This happens because we have a dozen products based on the same platform, and any documentation covering language-agnostic features of an IDE, such as editor features, version control, and general settings, would be reused. We have many sections in our docs that are shared between multiple publications.Even if there are several writers on a team each responsible for an isolated product area, they would all still add new topics, move content around, and remove obsolete topics, resulting in changes to the same configuration file. Apart from actual content files, a project may contain a bunch of configuration files, for example, a file that defines a table of contents.Areas of responsibility aren’t clearly defined.Īlthough this may indeed be a sign that you should revisit your content organization and roles, I could easily provide a few examples when such collaboration is justified.

A solution would be to break it up into several smaller articles. The document is too long as it describes several features owned by different writers.Some writers believe that multiple people having to contribute to the same file may signify the following problems: Many questioned the described workflow and highlighted that having to collaborate on the same file, pull and rebase changes daily, and resolve conflicts may be a sign of organizational and content management issues. Our first blog post on Git sparked discussions among different communities of tech writers.

Jetbrains phpstorm 10