There are plenty of advantages to using the OutSystems visual-based application development platform to create and update your applications — one of the biggest being that it helps you avoid technical debt. We’ve explored a few debt-busting features in our previous blog posts, including Visual Merge, TrueChange and the Architecture Dashboard. The one we’re focusing on in this blog post, however, isn’t so much a feature as it is a result of the OutSystems visual development platform itself (with a few extras): self-documentation.

We all know how important it is to document your code. It helps others (and future-you) understand it in order to update it as quickly and efficiently as possible — in other words, without encountering or creating technical debt.

Clearly documented code, whether written or visual, also helps with business continuity: Anyone new to your organization should be able to review it and get quickly up to speed with your entire app portfolio without having to read hundreds and hundreds of lines of code.

How Self-Documentation Works

As you work in OutSystems Studio, you are essentially creating an easily scannable visual representation of your app’s action flow, indicating where data is coming from and what logical decision points and/or transformations it encounters on its way to and from the user.

While this is happening, the Architecture Dashboard is using artificial intelligence (AI) to categorize your modules and apps into three layers:

  • The foundation layer, containing all reusable non-functional requirements
  • The core layer, where you implement business services around business concepts, rules, entities and more
  • The end-user layer, where your user interacts with your application

The Architecture Dashboard’s abilities to identify and highlight technical debt as well as drill down all the way to visual and written code make it an essential component of the OutSystems self-documentation capabilities.

Finally, OutSystems TrueChange works throughout the development process to identify and resolve coding conflicts to speed time to market while eliminating unplanned technical debt.

Getting the Most Out of Self-Documentation

Visual development, TrueChange and Architecture Dashboard are the biggest and most automated components of the OutSystems self-documentation feature set, but they aren’t the only ones.

OutSystems offers a number of tools to make your code easy to understand for future developers — including yourself. If you want to really leverage the power of these tools, have a look at our list of best practices and conventions that you can apply when developing your OutSystems applications.

  • Description fields: You’ll find description fields on just about any element in OutSystems: Variables, Actions, Entities, Entity Attributes, APIs, Folders and more. Taking advantage of these descriptions is invaluable in making your code reusable. Descriptions appear in a tooltip in the action flow and as a description when used as a function, and they’re persistent — so they reappear every time you use the element to which they’re attached.
  • Extension documentation: If you build your own extensions to use with your OutSystems applications, all the description fields for your actions and parameters in Integration Studio will transfer to your code, correctly formatted as a C# Documentation block on top of each method.
  • Action node labels: By default, OutSystems will give names to the different nodes in an action flow, but you can override them to give each node a descriptive name. Simply giving the nodes in your actions specific names and labels can make them instantly understandable.
  • OutDoc: This free and open application provides you with design documentation for your eSpaces and Solutions. OutDoc pulls out all of the components of your application along with all of your descriptions and creates a document that’s easy to read and parse. You can easily go in and export a PDF for a given module or an entire solution. This high-level documentation includes diagrams of your data model, references and dependencies, and processes.
  • Web service documentation: When you expose a REST web service from OutSystems, a documentation page will be automatically generated, as long as this capability is enabled under Advanced > Documentation.

Visualize Your Business without Tech Debt

As a visual-based application development platform, OutSystems makes it easy to communicate the intent behind your application design without any additional effort. On top of that, smart tools such as TrueChange and Architecture Dashboard offer even greater visibility into your entire portfolio so that future developers and architects can get up to speed quickly, bring new and improved applications to market faster, and eliminate technical debt.

To learn more about OutSystems and how it can help you eliminate technical debt, visit Stop Tech Debt.