How to add documentation to a particular application

How to add documentation to a particular application

  

Hi

I have documentation in pdf format, I want to add this documentation to a particular application as a module. Can you please suggest me how to do this.

Thanks in advance.

Hi Manjusha,

What exactly do you want to do with this documentation? Make it available to the user, or is it just something for the developers?

Kilian Hekhuis wrote:

Hi Manjusha,

What exactly do you want to do with this documentation? Make it available to the user, or is it just something for the developers?


Hi Kilian,

I want to make it available to the developers so that they can know what exactly my application represents.

Well, you can add a PDF to an eSpace as Resource. Click on the Data tab in Service Studio, right-click on the Resources folder (the very bottom one) and select "Import Resource".

There's two problems with this approach though:

  1. The resource is enclosed in the eSpace. Especially if the resource is large, this means longer upload and (probably) compile times. And every time you publish an eSpace, the eSpace is copied in the database, and so will be the Resource, wasting valuable space.
  2. Discoverability. Unless you explicitly tell developers where to find the PDF, they won't know where to look for it (they won't even know there is a PDF to start with). Also, many times a developer will just want to use an application or parts of it, instead of combing through the code, so if it's e.g. a Forge Component, they will just install and use it, without having a clue there's a PDF hidden somewhere in an eSpace.

And then there's the general problem with documentation: it will never be thorough enough, and it will always be out of date.

So I would advise against including documentation within the source code, except for strategic comments here and there, and just supply the PDF seperately for those interested.

Kilian Hekhuis wrote:

Well, you can add a PDF to an eSpace as Resource. Click on the Data tab in Service Studio, right-click on the Resources folder (the very bottom one) and select "Import Resource".

There's two problems with this approach though:

  1. The resource is enclosed in the eSpace. Especially if the resource is large, this means longer upload and (probably) compile times. And every time you publish an eSpace, the eSpace is copied in the database, and so will be the Resource, wasting valuable space.
  2. Discoverability. Unless you explicitly tell developers where to find the PDF, they won't know where to look for it (they won't even know there is a PDF to start with). Also, many times a developer will just want to use an application or parts of it, instead of combing through the code, so if it's e.g. a Forge Component, they will just install and use it, without having a clue there's a PDF hidden somewhere in an eSpace.

And then there's the general problem with documentation: it will never be thorough enough, and it will always be out of date.

So I would advise against including documentation within the source code, except for strategic comments here and there, and just supply the PDF seperately for those interested.


Thank you for your response. I'm preparing a reusable component so I want to add documentation for that as a HTML page. Is it possible to add HTML page as a separate module? If so how it can be implemented?

You can add the HTML page as a resource and deploy it to the base directory, or you can of course create the page in OutSystems itself.

Hi Manjusha,

I know it is not exactly what you ask, but did you look the ontrack application on forge?

It is a good app to help you manage your projects and it culd be a good way to keep your tech documentation and keep tracking about your development. You could customized it to include your pdfs too and you will also have a nice repository of info. 

https://www.outsystems.com/forge/component/1177/ontrack/


Best Regards.

Fabio.