Where is the documentation for Forge components?

Where is the documentation for Forge components?

  

Good afternoon!

A major challenge for me when using OutSystems is figuring out how to use components from the Forge correctly. I can't figure out what the accepted way to document a component is - when using components from the Forge I usually implement them by using a combination of interpreting function names/descriptions and looking at demos/the function implementations, but this tends to lead to (often not so) subtle bugs because I am not using the component in the intended way. I keep feeling like there is some hidden "Show documentation" button that I haven't found yet!

An example of a component that I've been struggling a lot with lately is the official/featured/supported Box connector component. It ships with a quite a lot of functions that do a lot of communication with the Box API under the hood, but there doesn't seem to be any instructions on how to use them. There is no obvious way to know whether or not a Box command will attempt to refresh its access tokens before executing, there is no way to tell that if you use JWT authentication it will create an app account in your Box organization and store it (linked to the currently logged in OS-user) in the database... in general: there doesn't seem to be any documentation of how the developers intend for you to use the component.

I've had the same experience with the rest of the Forge components I've tried - they seem to have a lot of valuable and useful structures/functions/boilerplate logic, but all lack an explanation as to how they should be used. Is the Forge community just not that documentation-focused, am I misunderstanding something fundamental or have I just been unlucky with the components I've needed?

Hello Mads,

Forge is a "community" repository.
Documentation is component owner's responsibility.
It is recommended to the component makers to provide examples and documentation, but usually (and often) this can be faulty. 

Better you can do is to ask the component owners to provide examples/documentation, or ask for help in the forum, when questions on how to use a component should be used.

Cheers

Eduardo Jauch wrote:

Hello Mads,

Forge is a "community" repository.
Documentation is component owner's responsibility.
It is recommended to the component makers to provide examples and documentation, but usually (and often) this can be faulty. 

Better you can do is to ask the component owners to provide examples/documentation, or ask for help in the forum, when questions on how to use a component should be used.

Cheers

Hello Eduardo, and thank you for your response!

Where would such examples/documentation be provided, assuming the component owner took the time to create it? In the "Details" pane in Forge?


Hi,

Usually, the examples will be in the component itself (in a separeted module) or in a different forge component (for some complex components, there is a different component with examples).

For documentation, it can be provided in the Details page, or in an external page, pointed in the Details page through link.


Cheers