documentation

Bug Report Template

The author of the book Deep Work talks about The Principle of Least Resistance.

> The Principle of Least Resistance: In a business setting, without clear feedback on the impact of various behaviors to the bottom line, we will tend toward behaviors that are easiest in the moment.
— Cal Newport - Deep Work
Shitty internal bug reports are an example of this. Over the years I've seen so much time and money wasted from badly written bug reports. The amount of back and forth between developer and reporter can really rack up.
> The text is wrong colour
— CEO's bug report
> I can’t create X
— Developer Y bug report
 

How To Encourage Good Bug Reporting

Provide Real Examples

Choose a real bug report that someone or yourself filed and go through it, looking at it's good and bad points.

Write Good Bug Reports Yourself

If you're writing bug reports for others, write really well detailed ones. It won't take long before they realise how useful it is.

Introduce a Template

Below is the bug report template I've used for the last few years. I usually customise it slightly depending on the project (iOS or macOS? Is there a dev server? etc). In the past I've also created a bookmarklet that automatically fills the text area of whatever tool we're using.


## iOSVersion## BuildVersion## Device## Server## LoginDetails## Isitreproducible? Yes / Occasionally / One Time / No ## StepstoProduce/Reproduce1. ...2. ...3. ...## ExpectedResults## ActualResults## Workarounds## OtherInformation

Documentation

I’ve worked with many companies over the years. The companies that work really well (remote or not) and can do a lot with a little (money and people) are the ones that document well.

By documentation, I mean asynchronous communication with your team:

  • Daily stand-ups. (the written type, not the “let’s disturb everyone to have a call” type)
  • Bug reports
  • Bug report updates
  • Labelling in Sketch files
  • Product roadmap
  • New feature ideas/research
  • Employee handbook
  • Shared password manager
  • Deployment logs
  • Commit messages
  • etc…

Writing documentation can be seen as a waste of time or money, however I have yet to see a instance where it has not made an improvement.

Next time someone interupts you by tapping you on the shoulder or @’ing you in Slack it might be worth making that knowledge more accessible.