ASG
IBM
Zystems
Cressida
Icon
Netflexity
 
  MQSeries.net
Search  Search       Tech Exchange      Education      Certifications      Library      Info Center      SupportPacs      LinkedIn  Search  Search                                                                   FAQ  FAQ   Usergroups  Usergroups
 
Register  ::  Log in Log in to check your private messages
 
RSS Feed - WebSphere MQ Support RSS Feed - Message Broker Support

MQSeries.net Forum IndexWebSphere Message Broker Supportjavadoc or similar for IIB flows

Post new topicReply to topic
javadoc or similar for IIB flows View previous topic :: View next topic
Author Message
souciance
PostPosted: Thu Nov 30, 2017 3:26 pm Post subject: javadoc or similar for IIB flows Reply with quote

Voyager

Joined: 29 Jun 2010
Posts: 83

Hello,

As a consultant one of the big pains at customers who use IIB is how to properly document IIB based integrations. Usually you end up drawing MS Visio diagrams, write excel docs or word docs.

Ideally the best way would be if the source code could generate the documentation like javadoc style.

How do you guys document your integrations? What level do you keep it at and do you use any automatic tools or is it plain old Office?

Souciance
Back to top
View user's profile Send private message
Vitor
PostPosted: Fri Dec 01, 2017 6:17 am Post subject: Re: javadoc or similar for IIB flows Reply with quote

Grand High Poobah

Joined: 11 Nov 2005
Posts: 24648
Location: Ohio, USA

souciance wrote:
How do you guys document your integrations?


We typically use the documentation feature of the IIB Toolkit.

souciance wrote:
Ideally the best way would be if the source code could generate the documentation like javadoc style.


What do you consider source code (in this context) for a SOAP or REST node?

As well as the generated documentation, we have a standard set of Visio blueprints and Word templates that are part of our delivery and review process. These document connections, endpoints and other parts that don't have "source code" (like SOAP and REST nodes).

We keep them up to date by building them into the code deployment process. BAR files don't go places unless there's updated, reviewed, signed off documentation going with them. We tried the honor system, but found that the development staff had no honor. So we built the stick.
_________________
Honesty is the best policy.
Insanity is the best defence.
Back to top
View user's profile Send private message
souciance
PostPosted: Sat Dec 02, 2017 7:38 am Post subject: Re: javadoc or similar for IIB flows Reply with quote

Voyager

Joined: 29 Jun 2010
Posts: 83

Vitor wrote:
souciance wrote:
How do you guys document your integrations?


We typically use the documentation feature of the IIB Toolkit.

souciance wrote:
Ideally the best way would be if the source code could generate the documentation like javadoc style.


What do you consider source code (in this context) for a SOAP or REST node?

As well as the generated documentation, we have a standard set of Visio blueprints and Word templates that are part of our delivery and review process. These document connections, endpoints and other parts that don't have "source code" (like SOAP and REST nodes).

We keep them up to date by building them into the code deployment process. BAR files don't go places unless there's updated, reviewed, signed off documentation going with them. We tried the honor system, but found that the development staff had no honor. So we built the stick.


Yeah we use Visio diagrams and word documents as well. But for some complicated integrations it can hours if not a couple of days to get the documentation right. Although document is invaluable it would be great if IIB provide better support for auto generating documentation.

You could provide some form of annotation for your esql that could be transformed to something similar to a javadoc. Well, at least it seems good old Office is here to stay for a while longer
Back to top
View user's profile Send private message
Vitor
PostPosted: Mon Dec 04, 2017 5:58 am Post subject: Re: javadoc or similar for IIB flows Reply with quote

Grand High Poobah

Joined: 11 Nov 2005
Posts: 24648
Location: Ohio, USA

souciance wrote:
You could provide some form of annotation for your esql that could be transformed to something similar to a javadoc.


Again I ask, what would you do for non-ESQL nodes like SOAPInput? Documenting those is potentially more useful in a problem / triage situation than the code.
_________________
Honesty is the best policy.
Insanity is the best defence.
Back to top
View user's profile Send private message
Display posts from previous:
Post new topicReply to topic Page 1 of 1

MQSeries.net Forum IndexWebSphere Message Broker Supportjavadoc or similar for IIB flows
Jump to:



You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
Protected by Anti-Spam ACP


Theme by Dustin Baccetti
Powered by phpBB 2001, 2002 phpBB Group

Copyright MQSeries.net. All rights reserved.