I'm working on a large project at the moment and I'm trying to document the communication protocol that sits on top of a message queue middleware.

The documentation is intended for another organisation that is going to be implementing a new back end to the client.

The messages format uses protocol buffers, so I'm less interested in describing the wire format.

I'm interested in documenting the interactions between the service and client. A typical interaction might be something like:

  1. Client subscribes to Channel1
  2. Client pushes RequestForStream to Queue1
  3. Service reads from Queue1 publishes StreamResponse (containing endpoint to subscribe to, Channel2) to Channel1 and if successful starts publishing notifications to Channel2
  4. Client receives from Channel1 and subscribes to Channel2
  5. More stuff...

How can I best document scenarios like this? Does anyone know of any examples of documented interactions with Queues and channels?

Edit: I am not writing a Message Queue. I am using a JMS-like middleware named Nirvana. I want to document the application built on top of the Message Queue system.

Edit 2: In UML how would I model a Queue or Channel? Would I show them on a sequence diagram?

  • 2
    Are UML communication or sequence diagrams an option for you?
    – Frank
    Feb 28, 2013 at 12:10
  • @Frank yes, but I didnt want to presume any possible solutions in my Q, if I'd said in UML, all the answers would be UML. Feb 28, 2013 at 13:25
  • Is your protocol similar to an existing public protocol? If so, did you look for how that protocol is documented? Also, it most certainly will be overkill, but making use of some government standards documents may help, because they are designed for the exact purpose you described. In particular, you are looking for an example Interface Design Description (IDD). A template for an IDD is defined in DI-IPSC-81436. But that might not help much if you can't find a corresponding example.
    – Dunk
    Feb 28, 2013 at 14:46

2 Answers 2


I am the author of pg_message_queue which is a very light-weight channel/queue system in PostgreSQL designed to facilitate database-level integration. Messages can then be forwarded to a heavier message queue, or the like, or they can just be processed. The use case is for things like "I want to send an email from the database" and helps solve the problem for PostgreSQL without really awkward transactional processing problems that could result.

Our documentation is at http://pgxn.org/dist/pg_message_queue/

I won't say it is the best documentation out there but it is sufficient for our use case. Compare to http://www.rabbitmq.com/documentation.html which is the rabbitmq documentation and you will see how different the requirements of the documentation in fact are.

But like all docs, keep your audience and use case in mind, and go through it conceptually and programmatically.

Edit Ok I see what I misunderstood. I would suggest starting at least with an outline of technical documentation. If you have it from someone else, great. If not, at least come up with an outline of what a technical programmer's manual should cover.

It sounds to me like you are looking at documenting a network protocol rather than an API. Sorry, I did read it and I missed that part. It's still not clear to me if this is direct over TCP, or over HTTP, or something else. To the extent you are reusing other protocols, the work is easier.

Either way, I would divide up the documentation into three sections. The first would cover message structure generally. This would include headers, message body specifications, etc. but would be at a general enough level to provide a reference for section 2.

Section 2 would cover the specifics for each message type. Again it depends on what exactly you are re-using how much depth you need to go into.

Section 3 would provide examples for how the communication would work using sets of mocked up messages.

  • I am not writing a Message Queue. I am using a JMS-like middleware named Nirvana. I want to document the application built on top of the Message Queue system. The audience is the programmer who write the services. Feb 28, 2013 at 11:17
  • I think you've misread the question - or perhaps just read the headline and not the body. Feb 28, 2013 at 11:30
  • I read it. My point is that the question as written is very vague. My qualifications are that I have written and documented a message queue. The key thing is to keep your audience in mind and pay attention to conceptual structure. What is appropriate for one audience and one use case may not be for another. In one case, perhaps sample code should be included. In another you want to provide detailed API specifications. The problem is there isn't a single answer here and it depends. Feb 28, 2013 at 11:57
  • You are well qualified to answer the question, but you have not understood it, your thinking is stuck the level lower, as that's what your experience is. I'll ask another Q for you, how would someone document the protocol that they have built on top of your framework? Feb 28, 2013 at 12:05
  • I have provided an example of the kind of thing that I need to document. Can you think of a better way than the numbered list? Feb 28, 2013 at 12:08

I have used pi-calculus to document and analysis high level processes. There isn't a standard language for pi-calculus, but for a tool I wrote I used a simple one-line per atomic step language, which would look something like:

process Client
    # initialise client process with the channel to subscribe to 
    recv self Init ( channel1 : channel, queue1 : channel ) 
    # send request to server
    send queue1 RequestForStream ( channel1 )
    # bind channel in response to channel2
    recv channel1 StreamResponse ( channel2 : channel )

        # either receive a notification or stop
        recv channel2 Notification ()
            goto loop
        recv channel2 Stop()

process Server
    new channel2
    # wait for request
    recv self RequestForStream ( client : channel )
    # send response to client with channel2 to send
    send client StreamResponse ( channel2 ) 
    # send notifications on channel2
    send channel2 Notification ()
    send channel2 Notification ()
    send channel2 Stop ()

# test
process Test
    c := start Client
    s := start Server

    send c Init ( c, s )

start Test

the extra stop parts are there as the tool is to detect deadlocks livelocks and races.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.