Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
We have a large biztalk EAI setup (+- 70 orchestrations, 200 send ports,...). Almost none of the orchestrations/ports have direct bindings. Every route is configured through filters.
Unfortunately, the time has come to document the integration scenario understandable to non-biztalk techies.
I wondered if there're any tools / word-excel-visio-... templates to document such a scenario.
It is not necessary to document orchestrain/map/code technical details, just the message flow.
(rcvport/location(with maps) -> orchestration(filter) -> sendport(s)(with filter, maps)
Thx;
Bart
You could use Business Process Modeling Notation (BPMN). I use it all the time to design and document Orchestrations.
Visit http://www.bpmn.org/documents.htm
Scroll down to Other Documents. The are stencils for Visio.
In my company we designed a documentation style for message flows based on UML.
We represent the BizTalk applications as components, and use the Ports and Interfaces on these components to represent connection points. We then use the Information flow connection between these interfaces.
We use Enterprise Architect from Sparx Systems to create these artifacts and views. The benefit of this tool is that it uses a repository based approach, so all artifacts can be reused for multiple views.
The downside to this appraoch is that you need to create all the views yourself. There is no easy way to generate this data from the source code or deployed BizTalk applications (that i know off), so you will need to create this documentation by hand.
I've always just used Visio to draw my own diagrams. In my opinion, having done this for 10 years, you have to be creative and not follow any one set standard. And from one client to the next, I don't always do it the same way. I'm trying to improve, but I don't think there is a "one size fits all" answer.
As with any doc, first, try to do something very high-level. Then zoom-in on the details in the next diagrams.
What is missing in general is how to describe data flow to/from port to port. For example, what if you debatch a file in a Receive Port? I used standard Visio flowcharting shapes, for example cylinder for pipeline, box for Port, etc... then connected them with lines. If you have just one map you can put that on the line. If you have a bunch of them, then it's difficult to represent. I try to put the map or the pipeline on the arrows.
I usually use the Cloud Symbol for sending data to other vendors or trading partners.
Sometimes I use the Server boxes of Visio, to indicate sending data to another server within our company, or even to an FTP server or Web Server at another company.
I also show the "MessageBox" has a port. For example, Receive Port is a box, then line to "MessageBox", then each Send that has a filter on it, comes out of that MessageBox. (I end up drawing a new "MessageBox" typically for each flow, to keep them separate.
For orchestrations, I have used SnagIt to screen capture the doc, then annotate with captions and arrows, and text in a Word document after the picture. (The problem is if you have wide or very complex orchestrations.)
Unfortunately, most the doc I do is not automated and not connected to the code or the bindings, so it can quickly become stale. I've never found "BizTalkDocumenter" to be that useful.
I sometimes use Tables in Word to show the developer artifacts and how they related (maps, schemas, pipelines...), and include a verbal description/commentary for each.
I agree with HSedidin above that BPMN might be worth trying, but even that, the audience would have to learn.
There is a "Stencil" pack for BizTalk avaiable for Vizio here: https://gallery.technet.microsoft.com/Collection-of-Visio-2013-0283d5f4, but I must admit that I haven't used it yet.
Related
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I need a personal archive tool to archive the programming algorithms, lessons, techniques and codes.
Something like a "Personal Wiki" that supports images attachments, code decoration, content categorization and search for any content at any time.
I know i can use an open source tool like forums or media wiki but i need something customized for this personal purpose.
Desktop tool or web tool.
For those who are search for the same purpose, I found some tools:
Here are some things I've tried with their pros and cons:
OneNote
Pros
Excellent ability to organise notes. You have have books containing section groups containing sections containing pages and subpages. I've got a book for Development, then a section group for Languages, then a section for Ruby, then pages for every topic within Ruby. The highlight here is that there's no penalty to creating dozens and dozens of pages on a given topic, helping you keep things organised when you get really deep into a specific topic. It's an easy mistake to just say "Yeah, a section for Languages, then a page for PHP", but before you know it the PHP page is half a mile long and you'll never sit down to properly re-read it again, it becomes a pain to find the info you want, etc.
Great support for multi-user notebooks. It properly keeps track of who added what and what got changed when, making co-operation easy.
Syntax highlighting can be done with the OneTastic plugin, which lets you define custom styles. Just define a custom style in a monospaced font with a special colour, and call it Code.
Support for tabular data, attached files, audio, video, etc, if you need that sort of thing.
Cons
Need to use a special app to consult it, so you can't just hit it from a work computer or the like.
Web app is clunky and lacking full features, I still haven't gotten a desktop notebook to properly sync as a web app notebook.
Search isn't the best.
MediaWiki
Pros
If you make it public, you can use Google on your notes, which is better than any other search.
CSS means it's easy to style and present it how you want without manually altering every bit of text like you'd need to in OneNote.
Because it's just a website like any other, you can access it from any device without installing anything or having to log in.
Export as ePub file, meaning you can read all your notes on your Kindle/ereader, really good for refreshing.
Any page can belong to multiple categories, which is nice.
Built in syntax highlighting with code tags.
Cons
Limited/clunky ability to organise in tiers, ultimately a fatal flaw for me.
Becomes a pain to quickly add notes to pages. (I would kill for a no-page-reload transition between read/edit modes!)
Reliant on an internet connection (usually not a problem, but something to be aware of).
Plaintext files in folders
Pros
Zero learning curve/adaptation.
Read them anywhere with no special software (tip: put them in a shared Dropbox folder, map an address on your domain to that folder).
Read natively on ereaders or convert to ebook format with no real effort.
Cons
No syntax highlighting, no image/audio/video media, no tabular data.
Hard to fuzzy search.
Edit conflicts if you're studying alongside someone.
Google Drive
Pros
Excellent support for sharing/co-operation
Good search
Good mobile support
Supports a lot of media
Cons
Tends to be slow to use
Presentation options tend to be frustrating
Reliant on internet connection
My personal recommendation: OneNote + Onetastic plugin, using all tiers/dividers, exported to PDF or multiple PDFs regularly so you can consult them from elsewhere.
Quoted from this link:
https://www.reddit.com/r/learnprogramming/comments/3acusr/how_to_take_notes_while_learning_programming/
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 2 years ago.
Improve this question
SAP GUI scripting is disabled on my employer's servers and I'm not in a position to change that, but I would very much like to automate some routine tasks of mine using some kind of scripting. I don't have (and I don't need) administrative access to the server, so this automation [afaik] has to revolve around SAP GUI in one way or another.
As an example, most repetitive task of mine that lacks automation is loading numerous reports with different parameters and exporting them to plain text files (to be aggregated and analyzed later in Excel).
What options should I look at? Mouse-and-keyboard automation tools come to mind first, but they are the least appealing ones at the moment.
For most of the options that are available, you will need at least the cooperation of the system administrators, and usually for good reasons - automation always gives you the option of destroying vast amounts of mission-critical data very fast. Depending on what you need to do - your question was not very clear on that - you might want to explore the following options:
Try to automate the data entry on the selection screen using selection variants. You can not only save static sets of data, but also include dynamic date calculations, and you can reduce the fields displayed until only the relevant fields are left.
Check whether you can schedule background jobs to have the reports run automatically at a given time and get the contents downloaded or mailed to you, depending on the capabilities of the report in question and the settings of your system.
For more complex flows, use the transaction recorder to check whether the task can be automated using batch input techniques. If this is possible, you could try to use the Legacy System Migration Workbench (LSMW) - although designed for data migration, you can use this tool as a "CSV-to-User-Command-Converter".
If you've come this far, it's not that hard to start writing ABAP programs, and we're back on topic for Stack Overflow... :-)
You can use Sikulli to automate tasks in SAP. They have a image recognition system where it can click buttons based on what it looks like. If you need to scroll through tables or something you are probably out of luck.
In my previous job I had to explain what SAP GUI scripting is to at least 2 dozen people and wait/follow for months to use it. Let say many people are still using my scripts there. It is always better to show your skills, So you better go proper channels. Also Using similar tools might not be welcomed If they are not enabling on their servers.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I'm investigating different documentation systems for a project keeping up. Most recently I've been using DITA and the DITA OT, but its complexity makes me want to shoot myself.
Are there any systems that provide the following functionality:
Markdown support
Reusable content (I can refer to previously defined paragraphs or terms)
Localization support
Preferably, free or open source
Preferably, allows for multiple output
I wish I could use Pandoc for this, but it doesn't appear to support reusable content.
Edit: I just ended up writing my own library for this: https://github.com/gjtorikian/markdown_conrefs
If you don't mind reStructuredText instead of markdown, Sphynx is worth a look.
You could use pandoc + pre or post processor.
That way you could easily implement snippet reuse.
This is a topic close to my heart. There's quite a lot of Markdown processor options out there, but at time of writing those are more a case of personal solutions to this persistent problem. We all tend to get frustrated, make something to help in the short term, and share it.
The challenge has been to extend this to something built for purpose and at scale. Which is where I've turned my focus to over the last few years. That includes first working on PressGang CCMS inside of a tech writing team at Red Hat, and then being inspired to spin out Corilla, a dedicated technical writing startup building the tool you require.
PressGang (the prototype)
Please refer to the PressGang CCMS project for an idea of what we did at Red Hat to build tools to solve this. The lead engineer did a run-through video that you can see on Vimeo, and I've created a public Amazon AMI if you wish to try it. It's not being maintained but it's all open source.
It's a relatively large stack written for the most part in Java, but was useful as a look into an open source project in this space. But with bias I'd suggest...
Corilla (the product)
We cofounded Corilla as an open source company to focus on bringing together the elements of content reuse and collaboration with the ease of Markdown and Asciidoc. I've spent years writing DocBook XML, and quickly built my own snippets for Sublime Text to minimise the considerable overhead of authoring in that markup. The tide is of course turning. We need easier ways to write faster, and we need them to be discoverable, reusable, and allow the entire team to generate the content in formats they require.
I'd encourage you to get involved with the beta, as the technical writing and developer community is driving the project, and as we solve our problems together. Being able to resource and drive this to market is far more rewarding than having to pick through incomplete processor chains. I've been there, it's time we did more.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
As the years go by we get more and more applications. Figuring out if one application is using a feature from another application can be hard. If we change something in application A, will something in application B break?
We have been using MediaWiki for documentation, but it's hard to keep the data up-to-date.
I think what we need is some kind of visual map of everything. And the possibility to create some sort of reference integrity? Any ideas?
I'm in the same boat and still trying to sell my peers on Enterprise Architect, a CASE tool. It's a round trip tool - code to diagrams to code is possible. It's a UML centric too - although it also supports other methods of notation that I'm unfamiliar with...
Here are some things to consider when selecting a tool for documenting designs (be they inter-system communication, or just designing the internals of a single app):
Usability of the tool. That is, how easy is it to not only create, but also maintain the data you're interested in.
Familiarity with the notation.
A. The notation, such as UML, must be one your staff understands. If you try using a UML tool with a few people understanding how to use it properly you will get a big ball of confusion as some people document things incorrectly, and someone who understands what the UML says to implement either spots the error, or goes ahead and implements the erroneously documented item. Conversely more sophisticated notations used by the adept will confound the uninitiated.
B. Documentation isn't/shouldn't be created only for the documenters exclusive use. So those who will be reading the documentation must understand what they're reading. So getting a tool with flexible output options is always a good choice.
Cost. There are far more advanced tools than Enterprise Architect. My reasoning for using this one tool is that due to lack of UML familiarity and high pressure schedules, leaves little room to educate myself or my peers beyond using basic structure diagrams. This tool easily facilitates such a use and is more stable than say StarUML. (I tried both, StarUML died on the reverse engineering of masses of code -- millions of lines) For small projects I found StarUML adequate for home use, up until I got vista installed. Being opensource, it's also free.
With all that said, you will always have to document what uses what, that means maintaining the documentation! That task is one few companies see the value in despite its obvious value to those who get to do it. . .
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 4 years ago.
Improve this question
In my analysis of the newer web platforms/applications, such as Drupal, Wordpress, and Salesforce, many of them create their software based on the concept of modularization: Where developers can create new extensions and applications without needing to change code in the "core" system maintained by the lead developers. In particular, I know Drupal uses a "hook" system, but I don't know much about the engine or design that implements it.
If you were to go down a path of creating an application and you wanted a system that allowed for modularization, where do you start? Is this a particular design pattern that everyone knows about? Is there a handbook that this paradigm tends to subscribe to? Are their any websites that discuss this type of development from the ground-up?
I know some people point directly to OOP, but that doesn't seem to be the same thing, entirely.
This particular system I'm planning leans more towards something like Salesforce, but it is not a CRM system.
For the sake of the question, please ignore the Buy vs. Build argument, as that consideration is already in the works. Right now, I'm researching the build aspect.
There are two ways to go around here, which one to take depends on how will your software behave.
One way is the plugin route, where people can install new code into the application modifying the relevant aspects. This route demands your application is installable and not only offered as a service (or else that you install and review code sent in by third parties, a nightmare).
The other way is to offer an API, which can be called by the relevant parties and make the application transfer control to code located elsewhere (a la Facebook apps) or make the application to do as the API commands enable the developer (a la Google Maps).
Even though the mechanisms vary and how to actually implement them differ, you have to, in any case, define
What freedom will I let the users have?
What services will I offer for programmers to customize the application?
and the most important thing:
How to enable this in my code while remaining secure and robust. This is usually done by sandboxing the code, validating inputs and potentially offering limited capabilities to the users.
In this context, hooks are predefined places in the code that call all the registered plugins' hook function, if defined, modifying the standard behavior of the application. For example, if you have a function that renders a background you can have
function renderBackground() {
foreach (Plugin p in getRegisteredPlugins()) {
if (p.rendersBackground) p.renderBackground();
}
//Standard background code if nothing got executed (or it still runs,
//according to needs)
}
In this case you have the 'renderBackground' hook that plugins can implement to change the background.
In an API way, the user application would call your service to get the background rendered
//other code
Background b = Salesforce2.AjaxRequest('getBackground',RGB(255,10,0));
//the app now has the result of calling you
This is all also related to the Hollywood principle, which is a good thing to apply, but sometimes it's just not practical.
The Plugin pattern from P of EAA is probably what you are after. Create a public interface for your service to which plugins (modules) can integrate to ad-hoc at runtime.
This is called a component architecture. It's really quite a big area, but some of the key important things here are:
composition of components (container components can contain any other component)
for example a grid should be able to contain other grids, or any other components
programming by interface (components are interacted with through known interfaces)
for example a view system that might ask a component to render itself (say in HTML, or it might be passed a render area and ask the view to draw into it directly
extensive use of dynamic registries (when a plugin is loaded, it registers itself with the appropriate registries)
a system for passing events to components (such as mouse clicks, cursor enter etc)
a notification
user management
and much much more!
If you're hosting the application, publish (and dogfood) a RESTful API.
If you're distributing software, look at OSGi.
Here's a small video that at least will give you some hints; the Lego Process [less than 2 minutes long]
There's also a complete recipe for how to create your own framework based extensively on Modularization...
The most important key element to make modularized software is to remember that it's purely [mostly] a matter of how loosely coupled you can create your systems. The more loosely coupled, the easier it is to modularize...