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 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 )

    loop:
    choice
        # either receive a notification or stop
        recv channel2 Notification ()
            goto loop
        recv channel2 Stop()
            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 ()
    stop


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

    send c Init ( c, s )
    stop


start Test

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