| |
|
RSS Feed - WebSphere MQ Support
|
RSS Feed - Message Broker Support
|
  |
|
| javadoc or similar for IIB flows |
« View previous topic :: View next topic » |
| Author |
Message
|
| souciance |
 Posted: Thu Nov 30, 2017 3:26 pm Post subject: javadoc or similar for IIB flows |
 |
|
Disciple
Joined: 29 Jun 2010
Posts: 169
|
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 |
|
 |
| Vitor |
| Posted: Fri Dec 01, 2017 6:17 am Post subject: Re: javadoc or similar for IIB flows |
|
|
Grand High Poobah
Joined: 11 Nov 2005
Posts: 26093
Location: Texas, 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 |
|
|
| souciance |
| Posted: Sat Dec 02, 2017 7:38 am Post subject: Re: javadoc or similar for IIB flows |
|
|
Disciple
Joined: 29 Jun 2010
Posts: 169
|
| 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 |
|
|
| Vitor |
| Posted: Mon Dec 04, 2017 5:58 am Post subject: Re: javadoc or similar for IIB flows |
|
|
Grand High Poobah
Joined: 11 Nov 2005
Posts: 26093
Location: Texas, 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 |
|
|
|
|
|
| |
|
Page 1 of 1 |
|
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
|
|
|
|
