Skip to Content (Press Enter)
UserImage.jpg
Manjusha Kavitam
52Views
6Comments
How to add documentation to a particular application
Question

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.

0
0
23 Jul 2018
Copy Link
2020-09-15 13-07-23
Kilian Hekhuis
 
MVP

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?

0
0
23 Jul 2018
Copy Link
UserImage.jpg
Manjusha Kavitam

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.

0
0
23 Jul 2018
Copy Link
2020-09-15 13-07-23
Kilian Hekhuis
 
MVP

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.

0
0
23 Jul 2018
Copy Link
UserImage.jpg
Manjusha Kavitam

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?

0
0
23 Jul 2018
Copy Link
2020-09-15 13-07-23
Kilian Hekhuis
 
MVP

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.

0
0
23 Jul 2018
Copy Link
2026-03-09 12-26-51
Fábio Fantato
 
MVP

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.

 

0
1
23 Jul 2018
Copy Link
Community GuidelinesBe kind and respectful, give credit to the original source of content, and search for duplicates before posting.