Make Work Better by Documentation

Sharing knowledge in a team is an ongoing challenge. Finding balance between writing documentation and keeping it up to date, and handling daily operations and discussing matters face to face or via chat is not an easy task. I’ve found written documentation to be well worth the time it takes. Here's two examples of how documentation has helped to make our work better.

Make uncertainties visible

Documenting software requirements has a profession of its own. But one doesn’t need to be an expert in requirements engineering to be able to enhance customer communication and ease the development with documentation.

Problem

I had a customer at work who wanted to integrate a 3rd party service. The service was under development at the same time that we started discussing integrating it. The service would replace old processes in the customer’s existing service. There were lots of questions about how the new service would function, and what exactly it would mean to replace existing functionality with it.

Solution

I sat down with one of my colleagues who knew the customer software. With pen and paper, we drew several sequence diagrams to represent current processes. Then we created sequence diagrams to propose how the new service would be integrated. We drew big question marks where we were unsure of the current process or how the new service would function. We even included questions for manual processes in the customer end to better understand what information the new service should provide.

Then I transformed the pictures from paper to digital form and included the diagrams to a wiki page. I gathered all questions to a table in the same wiki page. Next time we discussed with the customer, we went through the wiki page, answered all the questions and wrote a bunch more. The wiki page served well during the requirements gathering phase. It was liked by both the developers and the customer.

Take-aways

• Sequence diagrams are a lovely way to present processes.
• Table of questions, with an empty column for an answer, invites discussion.
• Wiki page with diagrams and question-answer tables serves well as documentation.

Bring clarity with meaningful ways

Managing development tasks, bug tickets and service requests can become a full-time job. When a team has several customers, and each customer has a lot going on, kanban boards can end up in a cluttered condition. More time is spent figuring out what to do instead of doing it.

Problem

We used a kanban board for service requests, bug tickets and sharing information with a customer. Their system was in beta test phase, and lots of questions and enhancement ideas were coming up. It was difficult for the team to keep up with the latest priorities. There was a weekly meeting with the customer, but information was poorly shared for those of the team who did not attend the meeting.

Solution

To have a common starting point, I listed all ongoing tickets and described their status in the very first agenda of weekly meetings. In the meeting, we agreed on a priority order for the tickets, and I wrote that down to the agenda, which became the meeting minutes on the fly.

For the next weekly meeting, again I gathered information for all ongoing tasks. It wasn’t a fast thing to do, because there were so many sources of information for the work we were doing for the customer. But it was worth it. Weekly meetings became easier to lead, when we had a ready-made skeleton to follow, instead of tumbling around the kanban board. Also, having written documentation ensured that the whole team was informed about work ongoing and priorities for the next week.

Take-aways

• Prepare for meetings with an agenda. Share it beforehand with everyone involved and store it in a place available for both the team and the customer.
• Write meeting minutes. An easy way is to transform the agenda to the minutes by updating the document during the meeting.
• Make sure the team knows there is documentation in the form of agenda/minutes.

Document when necessary

As we’ve seen, written documentation can help a lot when planning a new service or handling quickly changing requirements. Documenting must be allocated a time of its own. It might be difficult to take the time for writing documents, if it is not a common practice within your team.

Personal skills have a role to play, as well. Finding important information in the clutter of communication and getting it to a written form might not be easy for everyone. Leverage the various skills of your team and find the best ways of documenting your important matters.