P10 Documentation - Drop in Quality

P10 Documentation - Drop in Quality

  

Hello,

Does anyone else feel like there was a noticeable drop in quality in the P10 documentation? I mean, just compare the "Process Properties" documentation between P9 (link) and P10 (link). The P9 version has a lot of additional information and links in the "Obs." column, while the P10 version only has a brief description of each property.

I wonder what the reasoning was behind the decision to remove important information from the documentation.

Hi Aurelio,

As I understand it, OutSystem has used a new back-end system for the P10 help pages, which called for a rewrite of the these pages. I think the problem with the lack of completeness is known, and has the attention of OutSystems, but I agree that after more than a year they should be catching up.

Hello Aurelio,

What you noticed is a page scheduled for update. It's not the only one, since we need to review the docs from 9.1 for 10. We are sorry this may be perceived as a "drop of quality".

Is there a particular piece of information that you missed in documentation? Is there something we can assist with?

Hello Aurelio,

Thank you for your feedback. As a matter of fact, we know that there's still a lot of work to do to make the OutSystems 10 documentation as useful as possible while covering most of the product.

We are actively working on expanding the OutSystems 10 documentation right now. Let me also share with you that we intend to finish importing and updating all the information that was already available in 9.1 to 10 until the end of the year.

At the same time, we have also been investing in the mobile related topics of the product, such as the generation and troubleshooting of mobile apps, including the debugger capabilities.

Users like yourself provide important information that will allow us to determine which areas bring more value to the developers and that we should tackle first. So, we hope you don't mind that we'll reach out to you to obtain more context from your particular situation.

Thank you!

Hello Romeo and Ângela,

First of all, thank you very much for your responses.

In my particular case, I'm currently studying to take the Professional Developer certification exam. So if I want to, for instance, learn more about BPT, I'll select a process and hit F1 while in the process' properties pane. In P9, I'm taken to a page with links to a lot of additional information. In P10, I'm taken to a page that has just the descriptions of the process' properties, making it necessary for me to navigate through the documentation, looking for that additional information.

It's this easy, direct access to in-depth information that I miss the most.

Thanks!

Solution


Hi Aurelio,

Just to let you know that we’ve taken your feedback into consideration and we’ve made several improvements to our documentation pages.

We’ve also revisited our connection between Service Studio and Documentation, by creating more F1 links. We hope you’ve noticed it in your particular case of the Processes. Can you check it out?

We do want to keep improving so we’d love to hear more from you. Do you have anything else in mind regarding OutSystems 10 documentation?

By the way, let us finish by sharing with you the pages we’ve evolved lately:


Solution

hi Angela,

May be it is a good idea to add a new topic about Forge Component built by Outsystems as this OP concerns:

https://www.outsystems.com/forums/discussion/33789/where-is-the-documentation-for-forge-components/

https://www.outsystems.com/forums/discussion/33312/documentation-for-scope-of-web-page-variables/


regards,

indra


Hi Ângela,

Sorry for the late reply. I've taken a look at the Processes documentation and can see that you've made some clear improvements to it.

I still have one suggestion though. I'll once more use the Processes documentation as an example. Looking at the P9 documentation of the "Expose Process Entity" property, there's a link to an article with a lot of additional information regarding that property. The P10 documentation doesn't have that link. Having access to this kind of information right there next to the property's documentation is really useful to help us understand how exactly that property works.

Thanky you for the feedback and keep up the great work!

for example, the json serialize and json deserialize documentation has only tables... not a single explanation how to use them for someone new to it. There are too many gaps in the documentation. 

Jorge,

The documentation is a reference guide, not a how-to.

Kilian, here a counter example from the documentation that illustrate a how-to use a form to enter data. (I could give you dozens of examples of how-to from the documentation P10). I know there is a specific section for How-to in OS website, but the documentation itself has some examples of how-to as well:


https://success.outsystems.com/Documentation/10/Developing_an_Application/Design_UI/Forms/Use_a_Form_to_Enter_Data


or this: https://success.outsystems.com/Documentation/10/Developing_an_Application/Design_UI/Forms/Validate_Form_Inputs

You're right, in some cases there's indeed some how-to, forgot about that. But I'm not sure whether it's possible to do that in all cases.

Killian,

I think it's not unreasonable to expect the documentation to have at least a simple example showing how to use a given element.

I agree in theory, but I'm not sure whether that's always possible. Something to strive for, for sure!