Automating Message Documentation for a Corporate Wiki


Written by way of Martin Führlinger, Tool Engineer Backend


Welcome to the sixth submit on this message bus comparable weblog submit collection. I extremely counsel studying the others too, to get the total context. Those are: 

Now, I need to supply extra insights into our documentation round messages and the way we computerized this.

Message Documentation

Documentation is tricky. Regardless of who you ask, documentation is at all times laborious to create and maximum necessary stay up-to-the-minute. As at all times, we began with documenting our messages in our corporate wiki’s wisdom area. Every time new messages have been added or present ones modified, anyone had so as to add or replace them. The message subjects have been indexed in a matrix, containing the manufacturer, the subjects, the patrons, and a few further notes. It gave the look of this:

This procedure used to be gradual and error-prone. So we would have liked to strengthen this. 

The best way to Automate Documentation 

Right through certainly one of our Day of New Concepts (DONIs), some colleagues and myself began to paintings on a small carrier to routinely record the present messages in our device. We got here up with a beautiful easy carrier, named MessageDoc, simply being attentive to all imaginable messages, to be able to all routing keys (in finding information about routing right here), by way of being attentive to `#.#`.

Every time we obtain a message, we parse it and retailer its knowledge. This implies we retailer a record in a small MongoDB containing the messages meta information, just like the manufacturer, the message itself and a few extra attributes. That is completed in line with subject. The waft of receiving and storing may also be noticed within the following diagram.

msg doc receive flow

To peer how this looks as if in our database, here’s an instance: 

  "_id" : "pattern.up to date.altered",
  "manufacturer" : "samples",
  "description" : "",
  "shoppers" : [
    <list of consumers>
  "entities" : [ {
    "type" : "run_session",
    "updated_at" : ISODate("2020-11-11T14:56:02.304Z"),
    "example" : <complete message payload>,
  } ],
  "model" : 4124,
  "created_at" : ISODate("2019-11-28T11:15:26.105Z"),
  "updated_at" : ISODate("2020-11-12T06:00:12.950Z")

As we don’t need to retailer each unmarried message, we handiest replace the message’s content material as soon as an afternoon. We once in a while have polymorphic messages. This implies we’re sending various kinds of entities within the similar message sort. As an example, a “sample_message” may also be of sort “run_session”, “sleep_session” or others. We retailer just one instance in line with entity sort.

We all know who the manufacturer of a message is, because it is a part of the message payload (see how we outlined our message content material). Every time a record is written to mongodb, we additionally replace the patrons asynchronously. We completed this by way of querying the Rabbitmq API configuration by means of a HTTP request (the usage of the all-configuration trail), parsing it and updating all shoppers of all our saved messages. Information about “shoppers” may also be discovered within the first weblog submit on this collection.

msg doc mash processing

Construction a easy Internet-Interface

So to get entry to the saved knowledge with out querying the database immediately, we constructed a easy internet interface on best of this. Mainly, the review appears very similar to the former matrix within the wiki. It displays all subjects grouped in combination by way of the manufacturer.

msg doc overview

When getting access to an issue, the subject main points are proven, with all of the shoppers once more for this particular subject. This additionally method the patrons of an issue may also be other in the main points view, as e.g.”samples.created.finished” messages are ate up by way of different services and products than “samples.up to date.altered”. This subject element view additionally lets in so as to add some description to the subject.

msg doch topic detail

As discussed above, we retailer an instance message for each subject and each entity sort as soon as an afternoon. Those may also be proven too by way of increasing the corresponding entity hyperlink under.

msg doc msg detail

Making Handbook Message Documentation Out of date 

With this carrier in position, we have been in a position to deprecate the message documentation within the wiki. Even supposing we delete information saved within the message document carrier, it’s routinely recreating all of the knowledge. The one factor which might be misplaced are the extra descriptions in line with subject that have been added manually. This straightforward carrier, with not up to 1000 traces of code general, made guide documentation of messages and its content material out of date, and our existence more uncomplicated. 


Source link


Please enter your comment!
Please enter your name here