Building a WoW Repository on Git

By: Carlos Freire (Senior Software Engineer)

Here at Guidewire, most engineering teams define and publish Way of Working (WoW) documents to outline how work is executed, coordinated, and managed to achieve key product development goals. Historically, these WoW documents have been defined and stored on Confluence. And while it is a great tool for general knowledge sharing and collaboration, keeping this kind of documentation on Confluence has presented some challenges.

Before we dig into some of these challenges, let’s first elaborate on our definition of a WoW document.

What is a Way of Working document?

A WoW document describes how a team functions and executes tasks within their assigned area of responsibility. This includes guidelines, processes, and practices a team follows to get the work done, with every team member contributing and mutually agreeing to the document content before it is published.

A WoW document generally includes things like:

• Roles and responsibilities, including decision-making authority
• Social contracts or agreements to guide team behavior
• Code contribution and code review guidelines
• Estimation and priority definition guidelines
• Team ceremonies definition and management

Specific product or project information, internal schedules, and more detailed things like how to handle spikes are not included in WoW documents.

Why are WoW documents important?

A team’s WoW document is essential to getting everyone on the team on the same page to enhance collaboration, reduce misunderstandings, improve productivity, and foster a shared understanding of how work should be conducted.

Publishing and sharing a WoW document can avoid unnecessary debates about how to handle specific situations since the team has already reached an agreement on how those issues should be addressed. For example, every engineer has been on a team where the question “Did we estimate Tech Debt or not?” comes up during a refinement session.

With WoW documents, such questions need never be asked.

A WoW document is also valuable when someone new joins your team. It helps them quickly learn the team dynamics, how the team makes decisions, how communication flows, as well as to understand performance expectations.

The challenge of using Confluence

As described earlier, most teams at Guidewire have posted their WoW documents on Confluence. While this can work in practice, WoW documents have an essential attribute of memorializing a team’s shared understanding and agreement. The question becomes, how do you effectively perform the team review and editing activities in Confluence to reach that agreement?

In Confluence, there are two ways to perform collaborative editing: sync and async revisions.

Let’s explore the challenges of authoring WoW documents (i.e., page content) using each approach.

Sync revisions

With a synchronous editing approach, everyone on the team must block their calendar for a team meeting to create or review an existing WoW document in Confluence. These meetings are typically structured to have one engineer read through the document while the others discuss possible changes. While having everyone collaborate at the same time can get the job done, this approach presents several challenges to overcome:

• It is hard to keep the team engaged in the revision process if the document is too long or if there is more than one document to review.
• It is yet another meeting that breaks the flow of coding work for an engineer during the workday.
• It doesn’t allow for subsequent contributions if team members have other insights or suggestions to make after the meeting is over.

Async revisions

With an asynchronous review and revision approach, each engineer dedicates time to reading and proposing changes to the document. Confluence has two ways to capture this input from the team: inline comments or page-level comments. From a WoW document perspective, both methods are problematic:

• Reviewing comments posted inline can be complex, with people quickly losing context after several changes are made to the WoW document.
• Page comments primarily have context when they are posted and often lose relevance with each subsequent update or change to that page.

Confluence page history

While it might be a best practice, most users ignore describing the specific edits made to a Confluence page. So when it comes to WoW documents, it becomes impossible to understand what changes were made and how they contributed to the resulting team agreement.

Solution: A Git-based WoW Repository

Given the challenges described above, I thought to myself:

We use Git every single day as engineers, so why not use it to provide a more effective solution than Confluence?

The answer was obvious, so I built a WoW Repository for my team on Git.

A repository where development teams can author, review, and store their WoW documents and keep them updated.

A Git-based WoW Repository provided many advantages over Confluence, including better support for asynchronous revisions, more inclusive team editing, and better change history tracking.

Let’s explore them.

Async revisions

In Git, async revisions are enabled by the most effective revision process ever created: Pull Requests!

Changes and related discussions are contextualized all in one place, making it much easier to track down how the document evolved to its current state.

Inclusive editing

With Git, team members can propose a change anytime and anywhere. They don’t need to wait for the next formal revision of the WoW document, whether six days or six months from now.

Change history

Because we rely on Git commits to track changes, we can have an organized history of edits to our WoW documents.

Other Git capabilities

Git has many other capabilities, including Git blame, Git diff, and many more, that can help teams continuously review, evolve, and manage our WoW documents.

WoW Repository best practices

After one year of using the WoW repository in my team, I learned some lessons that can help your team to get the most out of that idea.

Repository naming format

To make your WoW repository easily searchable and shareable inside your company, you can follow the naming convention “[team name]-wow”. For example, we have the “wicklow-wow” repository for my Wicklow team at Guidewire (yes, we ❤️ Ireland! 🇮🇪).

Document format

WoW documents should be created in the format that suits your team better. For example, some teams prefer to use plain text files, while other teams prefer to use Markdown. However, the smartest teams will always use org files. 👅

Jokes apart, I recommend using some format that works well with your Git hosting service (BitBucket, GitHub, etc).

It means your team should be able to view and edit your WoW documents thru your Git UI, for example.

Just promise me you will not put Word files there, ok?

Revision requirements

Your team should agree on minimal team approval requirements for changes to WoW documents. An excellent initial rule is to require majority approval for changes. For example: with a team of five engineers, at least three must approve the change. You can easily configure your WoW Repository to follow this rule.

Links to Confluence

Given the extensive use of Confluence at Guidewire, most engineers will look to Confluence first to find WoW documents. To make it easy for them, place a link to your WoW Repository on your team’s Confluence page or where you usually stored your WoW files before.

What’s next?

If you liked the idea of using a WoW repository and want to create one for your team, I created a sample one that maybe inspires you and your team. You can check it out at: GitHub — carlosrvff/yourteam-wow: The WoW repository for the [YourTeam].

If you are interested in working on our Engineering teams building cutting-edge cloud technologies that make Guidewire the cloud leader in P&C insurance, please apply at https://careers.guidewire.com.