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 SupportGenerating a standard of documentation Process for IIB Apps

Post new topicReply to topic
Generating a standard of documentation Process for IIB Apps View previous topic :: View next topic
Author Message
urufberg
PostPosted: Mon May 06, 2019 3:54 pm Post subject: Generating a standard of documentation Process for IIB Apps Reply with quote

Apprentice

Joined: 08 Sep 2017
Posts: 25

Hi everyone!

I'm starting a process to revisit every IIB project I've been involved in the last 3 years, with the main focus of reading and improving the documentation generated in each of them by creating a standard.

Over the course of this time I've created a lot of documents (Diagrams, Texts, even using the integrated feature to generate documents) but never stablished a clear standard nor a process to release said documentation. So you know, by now documents look nothing alike the actual application .

I would really like to hear about other's experience doing this, what do you find more useful to get writted down, and what is a literal pain or worthless to both documentate and mantain.
There is a recent conversation in this thread but I would like to expand a little bit more.

Finally, my idea is to generate said standard in Markdown and post it somewhere in the near future so others can benefit from it.

If you feel like colaborating please do! I'm eager to hear about your opinion.

Thanks in advance
Back to top
View user's profile Send private message
Vitor
PostPosted: Tue May 07, 2019 4:59 am Post subject: Reply with quote

Grand High Poobah

Joined: 11 Nov 2005
Posts: 25855
Location: Texas, USA

I stand by my comments in the previous thread. To quote a well known alien:

Quote:
We do not claim perfection. But we have a system, and it works


(My purchase order for a giant robot keeps being denied though.....)
_________________
Honesty is the best policy.
Insanity is the best defence.
Back to top
View user's profile Send private message
urufberg
PostPosted: Tue May 07, 2019 8:59 am Post subject: Reply with quote

Apprentice

Joined: 08 Sep 2017
Posts: 25

This is by far the best quote of that thread:

Vitor wrote:
We tried the honor system, but found that the development staff had no honor. So we built the stick.


Actually now that I have you here (and If you don't mind sharing) I want to ask you some stuff (I didn't want to reopen a late 2017 post ).

a)When you said:
Vitor wrote:
We have a standard set of Visio blueprints


Are them for general purpouse (communications & interactions and overall process) or do you keep a blueprint to customize with specific functionality (let's say WS operations or flows & sublflows)?

b)How do you keep record of shared resources (for example in a shared library)? Behind of my idea of using Markdown (besides it's the cool stuff to do) is that is really simple to keep resources well encapsulated, separated of each other and is built into code.- But i'm thinking maybe there are other options with better pros and/or less cons.

Sorry to bring you to this, I really want to hear from experienced people but I can understand that giving answers can take up your time.

Anyway, thanks for the update!

PS: Please tell me if that robot thing goes up, I could use one too
Back to top
View user's profile Send private message
Vitor
PostPosted: Tue May 07, 2019 9:19 am Post subject: Reply with quote

Grand High Poobah

Joined: 11 Nov 2005
Posts: 25855
Location: Texas, USA

urufberg wrote:

a)When you said:
Vitor wrote:
We have a standard set of Visio blueprints


Are them for general purpouse (communications & interactions and overall process) or do you keep a blueprint to customize with specific functionality (let's say WS operations or flows & sublflows)?


They're much more general purpose and are principally intended to:
- demonstrate compliance with standards
- indicate to the support people how the thing is supposed to work

There's a more detailed Word document that goes to the operations/flow/subflow level that also goes to the support people. We also have built into the governance workflow ("the stick") a stage where the code staged for implementation is compared against it's diagram, so there is at least a close family resemblance.

urufberg wrote:

b)How do you keep record of shared resources (for example in a shared library)?


Getting code into shared libraries is why I need the giant robot; I can't build a big enough stick. Very common features (logging, data validation, that sort of thing) are shared, owned and documented by the IIB administrators centrally. After that, the development teams invent as many wheels as they think is necessary and they're caught (or more likely not) during code review and testing.

urufberg wrote:

Behind of my idea of using Markdown (besides it's the cool stuff to do) is that is really simple to keep resources well encapsulated, separated of each other and is built into code.- But i'm thinking maybe there are other options with better pros and/or less cons.


Good luck with that. I feel I've done well getting Visio and Word out of the developers; now you want this Markdown thing (which I confess I'd not heard of before) in the code. Why not just go all the way and make developers put useful comments in the code as well??

I repeat my question from the previous thread; where would you put the Markdown for non-code nodes like the HTTPRequest?

urufberg wrote:
Sorry to bring you to this


Not yet you're not, but that day will come.

urufberg wrote:
PS: Please tell me if that robot thing goes up, I could use one too


I'll do that. In the meantime, I got funding for a proof of concept doomsday machine; I'm calling it "The Static Code Analyzer". Those fool developers won't know what hit them! I'll destroy them all!!

*evil cackle*
_________________
Honesty is the best policy.
Insanity is the best defence.
Back to top
View user's profile Send private message
gbaddeley
PostPosted: Tue May 07, 2019 3:46 pm Post subject: Reply with quote

Jedi

Joined: 25 Mar 2003
Posts: 2039
Location: Melbourne, Australia

Over the last few years we have become Confluence ( https://www.atlassian.com/software/confluence ) converts. It allows docs to be easily maintained and edited in a flexible structure, with embedded diagrams etc. We are moving away from word docs, spreadsheets, visio etc. stored on Network Attached Servers (sorry, the forum does not permit use of the acronym) or the likes of MS sharepoint.
_________________
Glenn
Back to top
View user's profile Send private message
Vitor
PostPosted: Wed May 08, 2019 4:42 am Post subject: Reply with quote

Grand High Poobah

Joined: 11 Nov 2005
Posts: 25855
Location: Texas, USA

gbaddeley wrote:
Over the last few years we have become Confluence ( https://www.atlassian.com/software/confluence ) converts. It allows docs to be easily maintained and edited in a flexible structure, with embedded diagrams etc.


Interesting - the Agile people here use that and JIRA for development. Should I obtain access to it? Any gotchas or best practices you're happy to share?
_________________
Honesty is the best policy.
Insanity is the best defence.
Back to top
View user's profile Send private message
urufberg
PostPosted: Wed May 08, 2019 12:49 pm Post subject: Reply with quote

Apprentice

Joined: 08 Sep 2017
Posts: 25

gbaddeley wrote:
Over the last few years we have become Confluence ( https://www.atlassian.com/software/confluence ) converts. It allows docs to be easily maintained and edited in a flexible structure, with embedded diagrams etc.


Fun fact: my company is an official Atlassian Partner since a couple of months ago. That's mainly where I got the idea since we're already in course of migrating to the Confluence KB (which, if I'm not wrong, uses an Atlassian's flavour of Markdown).

Vitor wrote:
I repeat my question from the previous thread; where would you put the Markdown for non-code nodes like the HTTPRequest?


I'm not seeing the problem there (maybe I don't understand this completly?). Markdown allows you to insert images, links and even some types of UML diagrams. Also you can mantain references in your document as well as to others (not only by title but to a specific section of the document). It's really useful when used with a git repository since you can get the documentation in the same root of the code and reference it from other places (which I think it would help with the shared resources problem) and of course, track changes.

For me, the problem in using a Knowledge Base is that I almost always work as an outsourced developer, not in my company. This means I would need access to such a tool in every client, which we all know not always happens...

Thanks again for the input!
Back to top
View user's profile Send private message
gbaddeley
PostPosted: Wed May 08, 2019 3:44 pm Post subject: Reply with quote

Jedi

Joined: 25 Mar 2003
Posts: 2039
Location: Melbourne, Australia

Vitor wrote:
gbaddeley wrote:
Over the last few years we have become Confluence ( https://www.atlassian.com/software/confluence ) converts. It allows docs to be easily maintained and edited in a flexible structure, with embedded diagrams etc.

Interesting - the Agile people here use that and JIRA for development. Should I obtain access to it? Any gotchas or best practices you're happy to share?

Yup, we use Jira too, for operations workload management, not just development. Confluence and Jira have a massive number of versatile features, its really beyond the scope of this forum to cover gotchas or best practices. They need buy-in from senior management (for funding), and there needs to be a scrum master / business analsyt to define the usage processes and keep everyone in line.

Trello ( https://trello.com/ ) has some of the features of Jira, such as equivalent concepts for stories, epics and swim lanes. You might like to try that first on a small scale. It's free.
_________________
Glenn
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 SupportGenerating a standard of documentation Process for IIB Apps
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.