Every team will figure out their own unique ways of working through “Forming, Storming, Norming and Performing” - but here are some techniques that I’ve seen provide lots of value - usually with little effort!

✏ Why not take a note of each one you aren’t using yet as you read?

GitHub

PR Templates

Open source projects often have multiple PR templates, to help capture context on bug reports, feature requests, and security vulnerabilities.

In your team’s day-to-day repositories, it’s likely you aren’t using templates. Maybe they “get in the way” and “just get deleted”, but these two features might make it more interesting!

Markdown comments

GitHub uses MarkDown (their own special flavour of MarkDown, really) - and it supports comments:

<!-- Please enter the ticket number below (GitHub will autolink to Jira), e.g. JIRA-1234 -->
JIRA-420

<!--
For this feature/fix, please link any tests from other repositories too:
- [ ] e2e: E2E-PR-1337
- [ ] perf-tests: PERF-404
-->

These comments are only visible when editing - you can’t see them on the posted description. You can use comment to give friendly reminders on:

• Providing context
• Linking to the ticket (rather than paraphrasing all that context!)
• Ensuring tests (unit, integration, performance) are covered
  • You could give a commented-out checklist if you want

AutoLinks

In each GitHub repository, you can set up “AutoLinks”. They’re basically an autogenerated, tidy hyperlink.

The GitHub Docs give a good example - but I’ll extract a snippet and save you getting distracted:

• Reference prefix: JIRA-
• Target URL: https://jira.example.com/issue?query=<num>
• Preview: JIRA-123 is converted to https://jira.example.com/issue?query=123

Combined with templates, you can ensure that every PR has a short link to the relevant tickets. This is much better than just having the ticket number (and no link) in the title/description/branch/commits:

• It saves the PR author time in making these links
• It saves the reviewers time fishing around in Jira and getting distracted
• It ensures everyone has easily accessible context, so the PR description can focus on the actual changes

Until I knew this I was using an Espanso text expansion macro :JIRA to do similar, but this setup gives your whole team an awesome shared capability

Conventional comments

Stating the importance & intent of your message up front can make communication clearer, and decisions faster.

Read more in detail at https://conventionalcomments.org/, but basically comments on PRs can look more valuable like this:

issue: this mock never gets called!

praise: this method is really easy to read, and handles the logic very well

nitpick: these two tests could be combined

Compare the latter example to how it might be expressed without “conventional comments”:

These two tests could be combined, but it's not a blocker for this PR and I'll approve

Conventional commits

Commits can look like:

• docs: add javadocs for user-facing swagger api
• bug: fix a flaky test
• chore: bump dependency version x->y
• feat: AI face detection when user blinks

It could help you have a more atomic git history, which may make PRs easier to comb through. You can also use the prefixes to group changes, and make prettier changelogs.

Read more: https://www.conventionalcommits.org/en/v1.0.0/

Tickets / work capture

Make templates

• Context, task, ACs, key contacts,
• User stories

Templates are all about adding context in an organised way. Having this context gives your team more autonomy and interest in the problems, and can lead to better outcomes. Think “Context over control”

Knowledge management

How are you recording your knowledge? Probably in a few places! It might look like this:

• Slack (short term - threads can be linked, good for captured asynchronous discussion)
• Google Docs (also great for captured async discussion, but leaning towards )
• Confluence (longer-term storage for internal decisions - awkward to collaborate on, not good for regular updates)
• Websites (static sites like Hugo’s Doks & Docusaurus can make information presentable, searchable, and written in simple markdown & managed by e.g. Git)
• Some loose markdown files in various repos (maybe some readme.md)

To get someone up to speed on your project, you’d probably start with the higher-level, more organised/presentable formats. Hopefully there is a natural flow through the information, otherwise someone who knows the scenery may have to plan a route for you.

But what if there were tools that combined the strengths of these platforms. Are there any services that are:

• simple: are written in simple markdown-like language
• collaborative: many users can write in real-time
• efficient: easy to convert discussions into clean documentation
• searchable: text search, or even graph search (how do ideas and documentation naturally relate?)

Notion

I use Notion, which covers these points well. It’s becoming more and more popular, and I’ve seen a few companies using it. Despite appearing simple, there’s plenty of power features under the hood:

• You can create tables of data - and create views over them, filter, sort, label and organise in helpful ways
• You can make timelines, calendars
• You can use it like a task management system (GTD, four quadrants - whatever you want)
• You can use it as a sprint/kanban board

It’s powerful - even for free users. For businesses, it’s at least $15 per user, per month. That sounds like quite a lot, but it looks like Jira costs the same.

I’ve never worked in a company using it as a central tool in all the ways above - so I can’t actually vouch for it. Maybe it only works up to a certain scale of organisation - but maybe that could be your organisation.

Obsidian

I didn’t get far into Obsidian - the theory can get pretty deep, and there’s many methodologies. You might have heard of:

• “Second brain”, and
• “Zettelkasten”

The key concept is that ideas are related, and naturally link up (like in our brain). You can view them as a graph (looks like synapses in our brain), converge, and diverge thoughts whilst keeping them linked. There’s also a cool plugin system. I had a play and set up cloud sync to GitHub and OneDrive. I’ve already got years of notes in Notion, and didn’t quite get sold on Obsidian.

Arguably, the notes (and their relations!) might not be personal enough to be maximally useful for everyone. However, across a small team it could work really well. $50 per user, per year - plus about $100 a year for sync.

If you think you’re having problems in some of those areas, maybe try a different knowledge management system. This is totally not an advert ;) I’d just love to see first-hand how these tools could work for some teams instead of the usual Jira/Confluence fare! If you have some 💲 and some ⌛, your team could spike using these tools.

Discussions

Collaborative working

Visible, welcoming huddles

Is your team pairing and mobbing, but in private calls? It’s not transparent or welcoming - so consider this:

Take the number of devs you have, and divide by two. Make this many “pairing” Slack channels. It gives a space for everyone to pair, or form mobs. If someone needs help, it’s easy to hop in and out without the complexity of setting up more calls.

Remote pairing

Quality checks

• git hooks
• github actions has a broad marketplace