I like PlantUML for its super-simple syntax that allows me to create visualizations for complex operations or flows. Sometimes, a sequence diagram is needed to remove space between messages. And PlantUML supports it!

Just define !pragma teoz true, and the new Teoz engine processes a diagram. Add & to the start of a row to ignore the indent between messages.

@startuml
!pragma teoz true
actor Customer as C
participant "HTTP API" as API
database "Database" as DB

C -> API: Message
& API -> DB: Same message
@enduml

More about Teoz engine here: https://plantuml.com/teoz. It supports many more amazing functions to empower a sequence diagram.

Additionally, here is one more excellent website with PluntUML hacks: https://crashedmind.github.io/PlantUMLHitchhikersGuide/index.htmlAdditionally

Most developers don't like to write documentation. They find it boring. Especially if there is no documenting culture in a company. In the meantime, the same developers usually complain that there is no proper description of a company's services and architecture.

Raising the culture of documentation is a complex subject that requires a lot of effort and encompasses many aspects. However, I'd like to share an approach that can encourage developers to start documenting their development process.

Developers enjoy writing code, and one way to get them to start documenting is by showing them how they can use diagrams to explain how their code works. One tool that can help with this is PlantUML. PlantUML allows you to write code that will be displayed as a diagram.

Another similar tool is Mermaid. These are reliable formats that are typically supported by most version control and documentation systems such as Github, Gitlab, and Confluence. Below are some examples that are built by my teammates who hate writing documentation! I only renamed some titles.😃

However, it is most effective with new microservices or modules, as documenting legacy code, regardless of the method used, is neither enjoyable nor straightforward.

Mermaid

sequenceDiagram
    participant KF as Kafka
    
    box rgb(200, 100, 100) Internal domain
    participant ITM as SuperSerice1
    participant RDS as DataService
    end
    
    box rgb(100, 200, 100) Transaction domain 
    participant TRS as NDA_API
    end
    
    ITM->>KF: Consume XXX file event
    ITM->>RDS: Get XXX data by `no_id` and `hidden_id`
    RDS->>ITM: Return XXX data
    ITM->>TRS: Use `something_reference_id` or `something_link_id` from XXX data to get transaction data
    TRS->>ITM: Return something data
    ITM->>KF: Produce `DONE` event (for something_event table)
    ITM->>RDS: Mark the data as `PROCESSED`
    ITM->>KF: Produce the same event to different topic to update balance

Try to play with this example!

PluntUML

@startuml
() "Shared file storage" as FS
component Preprocessing as prep {
[preprocessor]
database DB as prepDB
[preprocessor] -- prepDB
}

[ETL] as ETL
package MainProcessing {
  [Data-service] as XXX
  component "MainProcessing services" as R {
    [...] as a1
    [...] as a2
    [...] as a3
  }
  database DB
}

package Something {
  [Data-service] as TRS
  database DB as TRDB
}


FS -- prep
prep -- ETL
XXX -- DB
R -- DB
ETL --> XXX: Load the data\nfrom files
ETL --> R: Kafka event\nthat a file\nis loaded
TRS -- TRDB
R -- TRS
@enduml

Try to play with this example!

Usually, a RACI matrix is a tool for project management. It helps to know who does what in a project. RACI stands for Responsible, Accountable, Consulted, Informed.

• The R, is for the person or team that does the work. They do the task.
• The A is for the boss. He is in charge. He makes sure the work is done right.
• C is for people who are asked before a decision is made. Their opinion is important.
• Finally, I is for people who need to know what happens after a decision is made.

Creating a RACI matrix for a team involves identifying the key roles within the team and the typical tasks or activities that occur during a sprint. Here’s a simplified example of how a RACI matrix might look for a scrum team by roles:

In a scrum team, the chart helps everyone know their job and what they need to do. It stops confusion and makes sure everyone knows what's going on.

There is a Scrum guide that describes all the responsibilities of a Scrum team. However, for a non-Scrum team, it is not always clear who is responsible for what. Therefore, we can create a RACI matrix for each person involved. For example, it is a different view, where we allow more people to be responsible for an action.

Identifying responsibilities is very useful for a non-Scrum team where the responsibilities of team members are not explicitly defined.

Moreover, a clear understanding of responsibilities in a team is essential during an organizational transformation. For example, when we resign from the scrum team, all responsibilities also change. This change is clearly visible within a matrix.