Introduction

Why do we need guides?

There are a lot of reasons why we write and maintain these guides. Some of those reasons:

• Usually there are multiple ways to do a particular thing. Most likely there is only one way that works best for our team. It’s best for every team member to stick to this way.
• We gained tons of experience successfully delivering software for more than 10 years. We want to maintain this experience and share it with every new team member and to everyone whom this information would be interesting.
• Everyone who has a deeper interest how we work will get more technical details about our work by reading these guides.

What should be written in the guides?

We use our experience and knowledge to discuss which way works best for us when there are multiple options. Those decisions need significant efforts. It’s more effective to once discuss decisions, write it down and look up it again once somebody raises the same question again.

If you hear some team member asking “which way do we use here?”, “how do we do this or that?”, “do we use this library or another library?” or something similar, then most likely this information should go to the guides.

Only current approaches should be presented in the guides.

What should not be written in the guides?

Outdated information should not be in the guides. Current guides should represent the current way we build software.

Guides should not contain too detailed information. It should be only detailed enough to describe the approach. Too much of details will make harder to understand the core idea. On the other hand, guides should not contain too abstract information.

General rules for guides

• Prefer American English to British English.
• Rules for bullet points:
  • The text introducing the list of bullet points should end with a colon.
  • Text following bullet point should start with capital letter, end with period.

Who should write guides?

Everyone in the team should write new guides and maintain existing ones. A person who raised a question fills new ticket in the Guides project (ideally, this ticket has some information about decisions). Later some team member picks this ticket when preparing for Brown Bag. This should eliminate outdated information in the guides.

How to contribute to guides

• Come up with new improvements or accept a ticket from the backlog.
• If necessary, have an initial discussion with team members to validate the main idea of your improvement.
• Create feature branch and update guides with information about this improvement.
• Use Grammarly to catch syntax and grammar errors in your changes.
• Create a pull request in Gitlab.
• Introduce your pull request to the team during your Brown Bag presentation.
• During the presentation discuss with team members what do they think about this improvement.
• Record the feedback in Gitlab as comments to your pull request.
• After presentation, make sure that owners of old merge requests present feedback fixes they were given last week.
• If there is no decisive opinion about some aspect of your pull request, create a new story in the backlog.
• Update your pull request according to the feedback you have received during Brown Bag presentation.
• Introduce updates to your pull request during the next week Brown Bag.
• Repeat this every week until everybody agrees with your changes and there are no constructive arguments against it from any team member.
• Mention everybody in your pull request who has not participated in Brown Bag presentations in the pull request.
• Make sure that everybody mentioned in the pull request has voted it up.
• Merge your pull request.