This note is a followup of previous note (Why formal definition of “things” is important).

I would like to categorise alignment situation into following buckets –

1. Meetings/discussions
2. Tasks in jira/trello/gitlab
3. Application/Services/systems/pipelines
4. etc.

Meetings/discussions

It’s quite easy. We need a board/paper to draw the topics being discussed. We draw some boxes to represent entities. We draw the options being argued upon. A simple table might look like below. The person co-ordinating the meeting/discussion can volunteer to do this –

| Options  | Pros | Cons | Winner |   |
|----------|------|------|--------|---|
| Option 1 | ...  | ..   |        |   |
| Option 2 | ..   | ...  |        |   |
|   ...    |      |      |        |   |

Also, whenever someone asks questions – “What do you mean by this?” , we might need to be patient enough to explain the intermediate parts. Personally I am more biased to visualised representation in a discussion.

Tasks in jira/trello/gitlab

It’s important to mention details in the task ticket. For example, when there is a multi step task, it helps a lot if all the steps are written upfront. This gives an early idea about which section of the system is the expected work for corresponding ticket. Any kind of context is helpful.

Instead of Just error, include where it happened, who faced it, basically a correct way to reproduce the error. If it’s not reproducible, at least mention where it happened, how it happened.

It takes time to write these details, but if we don’t write it, we might have to spend similar amount of time explaining the same thing over chat/face2face to the person working on it. Better to have it in the ticket.

Application/Services/systems/pipelines

Explaining a system out of nowhere isn’t easy. If the system is large/complex, that’s even harder. The idea is to take scientific approach – break it into pieces, flows, something like lego.

Here is one way to describe a system –
1. A bunch of blocks representing individual scripts/crons/modules/systems/storages…etc.
2. A set of entities representing data structures, the data that is being passed around
3. A set of lines, drawing connections among #1 and #2

There are many more ways to describe a system. We can write pages of documentation with system design diagrams. Coming up with workflows. Any such kind of representation helps people to discuss over a system. Those formal definition makes sure that both people are talking about the same piece. And that facilitates a healthy debate.

Categories: Software Engineering | No Comments »