Tips and Tricks for OutSystems Documentation

Documentation can be a divisive subject between developers. How much is too much? How little is too little? How should it be formatted? Do you need an external documentation resource or are the code comments and definitions enough?

We’ve all worked on projects from other developers where we can’t make heads or tails of what is going on. In fact, if you look at an application you built a year ago, sometimes it can feel like it was written by someone else!

With OutSystems, you are given the benefit that your code becomes its own documentation. Following an action flow should be straightforward and easy to understand. Modern programmers rarely write flow-charts, but they really are one of the best ways to understand a method.

In OutSystems, you are also you are given a set of tools that can help this process. The platform encourages programmers to take time to fill out descriptions and make readable actions and screens. This eliminates a lot of the pain of traditional documentation.

While you are at it, make yourself familiar with the OutSystems best practices. If you are following them, you will immediately have code that is easier to understand and pass on to another OS Developer. Things like “Meaningful names (e.g. ‘Customer’ instead of ‘Cstr’)” and “Set the example string of Expressions” can make screens and actions easier to understand.

Here’s how OutSystems makes it easy to document as you go and simplifies the sharing of documentation. I’ll also share a few tips that I’ve learned from years of documenting code in OutSystems.

OutSystems organizes documentation for you

Across the platform, OutSystems makes it easy to make your code more readable.

Fill out your description fields
Across all of OutSystems, there are description fields. Really, they are all over. Web Screens/Blocks, Variables, Actions, Entities, Entity Attributes, APIs, Folders — the list goes on and on.

These descriptions are invaluable when it comes to re-usability of your code, and if you simply document as you go it is not a large lift. As an example, when you create a description for an action, that description will re-appear every time you use it. These descriptions appear in a tooltip in the action flow and as a description when being used as a function.

Label your action nodes!
In addition to descriptions, simply giving the nodes in your actions good names and labels can make them instantly understandable. By default, OutSystems will give names to the different nodes in an action flow, but all of these can be overridden. This allows you to give each node a descriptive name.

Descriptions in extensions become code comments
So you’re breaking out your Visual Studio and writing an extension? Well, make sure to fill out all the descriptions for your actions and parameters in Integration Studio. Now look at that! OutSystems correctly formats a C# Documentation block on top of each method to make even your non-low-code easily readable.

Tools to share your documentation

Great, you filled out all your descriptions and gave all your variables good names. Now you want a way to show off the documentation you made, or attach to a change request. OutSystems has got you covered.

OutDoc
OutDoc is a Forge component created by OutSystems that automatically generates documentation for your applications. OutDoc pulls out all of the components of your application along with all of your descriptions and creates an easy to read and parse document. You can easily go in and export a PDF for a given module or an entire solution.

Like all OutSystems Forge components, this exists as an example for your own creativity. If you don’t think the OutDoc is pretty enough, open it up and adjust it to fit your style. If you want to post your documentation automatically to a service, use OutDoc as a starting point. Go wild! At Boston NextStep last year I saw OutDoc being used to create a version/change control system!

Web service documentation
When you expose a REST web service from OutSystems, a documentation page will be automatically generated as long it is enabled under Advanced > Documentation.

The generated public documentation page can be easily shared with anyone trying to consume your exposed web service. The documentation can be found at the base URL of the web service. It gives the structure for the REST calls and includes your endpoint descriptions under Implementation Notes.

The description for the entire web service can be written in markdown, meaning you can include better formatting as well as external links. Here is the description for the provided example.

Some tips for OutSystems developers

Less is more
Now that I’ve spent all this time telling you to fill out your descriptions for actions and variables, I will let you off the hook. If you write descriptive names for your actions and variables, descriptions may not even be required. For example, an action with the Name “DeleteUser” with a single input of “UserId” does not need much more description.

OutSystems gives you the ability to add comments to either your UI or action flows. In general, these should only be used for very complex logic. If you need to explain yourself, there is a good chance you could make your flow easier to understand.

Don’t hide logic
The “If” inline function can be extremely useful for more complicated logic that needs to be completed inside of an assignment. However, it should not take the place of an “If” Node in an action or an “If” widget on a web screen. By hiding this logic, you lose the inherent benefit in OutSystems of having your logic easily understandable as a flowchart.

Each assign should do one thing
Each assign node allows you to assign as many variables as you want. This is great for setting up all of the attributes of an entity or a structure. Resist the urge to do multiple things in one assign. As with the “Don’t hide logic” example, this might make for a cleaner (looking) action flow, but it hides the logic inside of the assign. Essentially, if you can’t think up a succinct label that describes the multiple assigns you are performing, then you’re probably doing too much.

OutSystems is a visual platform, both in its front and back end implementations, allowing you to easily communicate the intention of a design. On top of that, it has easy to follow standards and tools to clarify the purpose and function of components. If you are conscious and notate as you go, you should never have to worry about the dreaded documentation debate again!