Encourage developers to write documentation

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!