The Virtue of Laziness

October 13, 2016Antoine Toubhans4 min read

thumbnail

The fable

When I joined the e-annuaire project, the team used to spend half a man-day per sprint writing documentation for the end-user support (EUS). When it was my turn, I screwed my courage to the sticking place and opened the Google doc:

gg-doc

Bunches of screenshots of the app, where overlaid yellow boxes are referenced on spreadsheets like this:

gg-sheet

The spreadsheet details the origin of each piece of information referenced on any page of the app, and my role was to update them one by one.
I clicked on the spreadsheet to open edition mode and... Uh, what??

cereal-guy

Dammit! Screenshot images were simply pasted so I cannot edit the spreadsheet :( I ended up creating a real spreadsheet and copying information from screenshots and I cursed the gods for what was arguably a boring work.

(Re)Act!

The boredom was the initial trigger for us to react, though this is not a valid business reason; the EUS team needs documentation material.

Filling a powerpoint presentation with ever evolving business rules is a waste of our abilities. Spreadsheets lack maintainability and we felt we should do something about it.

The support team

The support team deal with over 30 applications. In theory, anybody in the team should be able to answer any support demand on any application. In practice, each team member became an expert about 3-4 applications and our application only had a couple of experts who knew it well.

This organization introduces a single point of failure: if the two experts are missing, inexperienced team members will have to handle the app and responding time will skyrocket. Our application is critical so that's a big deal.

If the specialization of the support team disappears, so does the the single point of failure! And guess what lead the people to specialize? Poor documentation!

What is a good documentation?

A good documentation is:

  • Maintainable: the documentation stays consistent with the application and team members can easily update it. That's why self-documenting code is so popular. The easier the documentation can be updated, the more up-to-date it is.
  • Shareable: only one version of the documentation exists and knowledge is available to other team members
  • Available: distance between the problem and the solution should be as short as possible

What does it mean for our application?

So we start thinking about how to build up a documentation that is simultaneously maintainable, shareable and available.

A paper-printed documentation follows none of the three principles.

SharePoints, Google slides and their avatars are shareable but not available i.e., there is no guarantee that each support team member has access to the latest document. Most importantly, they are definitely not maintainable (see ##The fable).

In order to be available, the documentation must be reachable where the user encounters a problem i.e., in the app itself. Let’s take an example: a user call the EUS because there is a wrong phone number on a page:

e-annuaire-tel

For some reason, the guy answering the phone knows nothing about the e-annuaire. In order to help him, we implemented a feature displaying bubbles that appear when you click on a 'show help' button:

e-annuaire-aide-tel-readonly

Valuable information appear under the phone number, hence the documentation is available. Now, assume the support team member reads the bubble and calls Ms Martin and discovers she left and that Ms Smith should be called. The information in the bubble needs a refresh, so we implement a feature letting support administrate help content:

e-annuaire-aide-admin

Therefore, the documentation is maintainable. Finally, we ensure that every support team member sees the same help contents so that the documentation is shareable as well.

How did we do it?

Instead of spending half a man-day writing documentation, we suggested to the PO to onboard a "proof of concept" ticket. Within a week, we had bubbles in profile pages. Both the PO and the EUS team were very enthusiastic so we onboard more tickets to improve it: we spread bubbles on all pages, letting people administrate bubbles and adding contents depending on your role in the app (not only EUS team member).

It turned out to be a huge success: the PO and EUS team administrate help content themselves and the overall cost for developing the feature was less 3 man-days, compared to 0.5 man-day per sprint (and it is sprint #95)!

It was laziness that drove us first, but laziness alone is useless unless you turn it into a solution that is profitable to everybody.

Antoine Toubhans

Antoine Toubhans

Web Developer at Theodo