The JetBrains Blog

2023-07-04 13:08:12

Tech Writer’s Git Story: From Isolation To Collaboration

When I joined JetBrains back in 2014 as a senior technical writer, our team consisted of 5 documentarians covering 6 products.

We sat together in a separate room and kept our door closed most of the time, rarely mingling with any developers. We’d see them at the daily IntelliJ IDEA standup, but the team was already several dozen strong, and we didn’t feel like boring them with the details of our humble routine.

The process we had for documenting new features was as follows: there was a “To be documented” tag in our internal issue tracking system, YouTrack, and it was the developers’ responsibility to put this tag on any issue that they thought affected documentation. If they added it to the issue, we’d document the new functionality, but if they ever forgot to tag it – “helaas pindakaas”, as they say in the Netherlands.

There was no single source of truth as to which features would go into the release version, there was little forward planning, and our tasks were often random and haphazard.

Developer sources were stored in a Git repository and documentation sources were versioned by Perforce. Each writer owned a portion of the documentation related to a specific area, subsystem, or product, and we rarely contributed to each other’s files. Whenever one of us needed to make changes to a common configuration file – the one that declared the Table of Contents, for example – we’d write a message to our Skype chat (there was no Slack in those days) saying something like: “I’m checking out file X for editing, please don’t touch it until I’m done.” And then, once we’d finished, we’d write: “I’ve checked it back in. Kindly download the latest version from the depot”. This meant there was no conflict resolution process, little collaboration within the writers’ team, and absolutely zero collaboration with developers. The review process was practically non-existent. We basically just sent the developers a link to a staged version, not the source code. This meant that they couldn’t leave any comments or suggest any changes… unless they sent their feedback via email, which is really inconvenient.

And then we migrated to an internally built IntelliJ-based toolset – an early prototype of what’s now known as Writerside and decided to switch to Git.

This was a game changer!

In the beginning, adopting Git looked like yet another challenge on top of the mountain we were already facing. It looked too unfamiliar and complicated. It had many advanced features as well as commands that could accept arguments. But the good news was that we didn’t have to worry too much about all those features. We only needed to understand the basic workflows in order to get started versioning documents with Git. There was no need to learn the commands either since all the actions we’d ever need to perform could be called from the UI built into the IntelliJ-based IDEs.

Our new workflow

Git is a distributed version control system. Each contributor has a local copy of the repository and its entire history. Unlike Perforce, there’s no single central storage that serves as a library, where you take a book off the shelf, read it, and then put it back, with nobody else having access to it while you’re reading it.

The fact that JetBrains IDEs are based on the common IntelliJ Platform meant that there was a lot of content that could be shared. Therefore, establishing a collaborative approach was our main goal.

Here’s the new workflow we adopted:

• Each morning you updateyour project, which means that you pull changes from the remote repository and incorporate them into your local copy. This is all done automatically with a single action. There are two methods of incorporating remote changes: rebase or merge. We recommend using rebaseas this won’t create extraneous automatic commits, and your history will be cleaner.

• You then work on the content. When you’ve made changes that you’re ready to share with others, you commit them locally.

• Next, you updateyour project again to make sure your local copy is up to date, and only then pushyour changes to the remote. If someone has made changes to the same files, you’ll be prompted to resolve conflicts. This can be done in a three-way diff tool that shows your local copy and the version from the remote, with the central pane serving as a full-fledged editor where you can preview or edit the resulting version.

• Push your changes to the remote. And now you’re done!

This is actually all you need to learn to get started with Git.

How this helped

Switching to Git helped solve the following issues:

• Collaboration within the team. Following the switch, we could now truly collaborate on the sources comprising the big project to which we were all contributing. By that time, the team was growing quickly just like the number of JetBrains IDEs. Being able to simultaneously work on the same source files to customize and adjust shared content to a specific IDE was a real time-saver. We could now reuse content and take advantage of single-sourcing it instead of copy-pasting and duplicating similar chunks of content.

• Collaboration with developers. Now that we followed the same processes as the developers, it became much easier to establish a review process. We’d just need to create a review in the same way developers normally would and then assign it to the developer who’s implemented the feature we’re describing. We’d also include a link to a staged version of the document in the comments. This way, developers could see both the sources, as well as how documents would actually look on the web. It was now much easier for them to comment on the source files and even suggest changes via pull requests. They were also able to see the differences between versions, enabling them to focus exclusively on the changed portion of a document.

Last but not least, it helped us get noticed and establish better communication between writers and developers. This ultimately resulted in writers earning the trust of developers, leading to us eventually establishing a review process for UI texts where technical writers were allowed to commit to source code – something we couldn’t have even dreamed of back when we started.

---

https://blog.jetbrains.com/writerside/2023/07/tech-writer-s-git-story-from-isolation-to-collaboration/