search

OxalisCommunity / oxalis

Oxalis - PEPPOL Access Point open source implementation - Core component
Other
119 stars 89 forks source link

[documentation] The documentation needs major improvements #672

Closed karelkryda closed 1 month ago

karelkryda commented 1 month ago

Hi,

We recently implemented Oxalis standalone as a sender and Oxalis server as a receiver running in a Tomcat instance. During the implementation, we noticed a lot of problems with the documentation, which is very simplified and sometimes not even understandable. This problem affects both Oxalis itself and the AS4 plugin.

The list of components is inconsistent, it is not obvious which component can be used for which part of the job, the installation and use of each component is also described very vaguely.

The documentation is very messy in places and we had to figure out a lot of things on our own. For example, we only found out from the code that you can use not only the file path as input parameter -f, but also the directory path or use - to read from the console.

I would like to ask you to spend some time to edit and improve the documentation, which is very important.

Thank you in advance for your understanding

aaron-kumar commented 1 month ago

@karelkryda : Oxalis is Open source project and we are already working on improved documentation for our paying members. For membership details, please refer: https://www.oxalis.network/join

We also tried to provide minimal documentation for non-paying member. Please refer: https://github.com/OxalisCommunity/oxalis/wiki.
Since Oxalis is Open Source Project, so please feel free to contribute. At least, add your 2 cents to the documentation by adding the issue you faced during deployment. "No one has ever become poor by giving."

karelkryda commented 1 month ago

Hi @aaron-kumar, I don't think documentation is something that should be hidden behind a paywall. Plus the membership fee is very high in my eyes.

The problem is that you are the person who knows your software and knows what it can or can't do. I'm not sure I'm the right person to create documentation for your software. The documentation basically contains the bulk of the "To be documented" sections.