In the previous post, you could learn why visibility is extremely important in IT. If you’re still missing ideas on how to achieve better visibility, read this post. I present you 9 concepts of how you can increase visibility in a typical programming project.

1. Introduce decision log

That is, start documenting your decisions.

Discussing and understanding architectural decisions (which were made but never written down) between developers can take ages. Usually what’s missing in the discussion is historical context, that can address all the controversies and cut the discussion short.

To prevent such situation, proactively document your architectural decisions in a decision log.

There are plenty of templates out there for decision logs. Personally, I think only two things are important about the decision log:

  • It should be simple (to encourage using it)
  • It should live the repo

2. Keep README short

You can care about README on many levels of visibility. Please execute in order 🙂 :

  1. have README at all.
  2. keep README up-to-date. Updating README should be a part of Definition of Done. If you can’t execute this step, see Slow down.
  3. keep README short. Meaning, a new person in the project should be able to read it all, get all the needed information, but not be overwhelmed. Not everything needs to be known the first week, am I right?

Even though long README seems “more visible” than a short one, most important information doesn’t belong to README. Thank you for wanting to communicate about technical details, but please don’t do it in README. Create a Wiki page, update decision log, or write it on your private Slack channel.

Short README means it will be used by developers on a daily basis. Ideally, to communicate that something happens to the setup, config, or dependencies of the project, all you have to do is updating the README.

3. Introduce shutdown ritual

There’s a chance that people in your team, despite best intentions, forget to do their daily chore. Some of it would greatly increase visibility – daily update on Jira board, inbox zero e-mail, git push after a workday, etc.

I’ve been there. I used to forget to cultivate good habits even though I understood their importance and wanted to keep them.

What helped me was a concept I learned from the book Deep Work. It’s the shutdown ritual – a to-do checklist to be filled up right before you end your workday.

My personal checklist includes:

  • update Jira board
  • read emails (reply if necessary, aim for inbox zero)
  • read Slack (reply if necessary, aim for zero unread)
  • git push everything
  • work log you day

Notice how each of those steps increase your daily visiblity.

4. Invest in automated tests

Consider tests as extremely visible specification of your project.

  • they are committed to a visible place (repo)
  • they communicate what the code is about
  • sometimes they overcommunicate the intention, but for good. Generally, you never know when they are useful. Therefore, it’s easy to underestimate their value

For the sake of visibility, you have to care about the rising trend of test coverage.

  • If you have high test coverage, keep up the good work
  • If you have low test coverage, focus on increasing it (you may need to Slow Down along the way)
  • If you have no tests – start writing them

5. Don’t write private messages

Read more.

6. Aim for clear action points

Written trumps spoken. Whenever a relevant decision is made (for example, on a meeting or face to face conversation), write it down.

As simple as it is, it’s a good way to increase visibility (think of people who weren’t on a meeting; think of yourself in a week). Also, it’s a great way to overcome false-consensus bias.

Action points should clearly address three questions:

  • who?
  • what?
  • when?

To be specific, these are not action points to me:

  • We should have a style guide by Monday (missing “who”)
  • Everybody should be more involved (missing clear “what”)
  • Everybody should try more pair programming with Bartek (missing “when”)

7. Steer communication to public channels

When asked a question in a private message, reply: “Can we continue on a public channel?“

Usually, if there’s enough awareness of the importance of visibility, asking people directly is an impulse and can easily be steered like this without problems.

8. Personal Slack channels

Create a channel for every developer (#dev-bartek, #dev-robert and so on). Think of it as a company-wide Twitter account.

Its primary purpose: the owner of a channel pushes dozens of micro-updates of what’s currently on their plate:

  • Emergency, I need to go, will be AFK for 1 hour
  • … I’m back
  • I’m struggling with Y
  • … I finally overcame the struggles with Y
  • Pull Request almost ready
  • … won’t make it today with the Pull Request. It’ll come tomorrow morning

Eventually, there will be no need to micromanage people who frequently update their status on a personal channel.

Personal channels gracefully solve problems like “Where do I put this message?“. If you feel that something should be communicated, but belongs to nowhere, post it in your personal channel.

There’s also a secondary purpose of personal channels. Other people can ask questions that they think should be visible:

  • Where will you have X done?
  • How did you learn Y?
  • Will you be available tomorrow?

9. Slow down

There’s a good chance that you already have some arrangements to increase visibility, but developers don’t stick to it. A common example: Definition of Done and Definition of Ready tend to be neglected.

This could mean that your velocity is too high for current capacity. Maybe try to do less, but better?

10 stories in a sprint “with a lick and a promise” or 5 stories with proper documentation, tests, README updates? The decision is yours.

In my book, doing less but better is the right way to slowly but surely pay off technical debt and documentation gaps, and still deliver.

Wrap up

Here’s the whole list one again. 9 ways to improve visibility in your project:

  1. Introduce decision log
  2. Keep README short
  3. Introduce shutdown ritual
  4. Invest in automated tests
  5. Don’t write private messages
  6. Aim for clear action points
  7. Steer communication to public channels
  8. Personal Slack channels
  9. Slow down

Feel free to share in the comments your quick wins on how you increase visibility in IT projects!