Sylius: Documentation about Shipping Component are out of date

[Konafets]

The docs about Shipping Component is outdated and misleading. Additional it lacks on proper explanation of the concepts.

Issues are:

• non existent classes are mentioned as described in #9855.
• default Shipment state is wrong https://docs.sylius.com/en/latest/components_and_bundles/components/Shipping/state_machine.html
• The available states are wrong. See states at vendor/sylius/sylius/src/Sylius/Component/Shipping/Model/ShipmentInterface.php
• Class ShipmentItem does not exist

Furthermore the concept of all the classes are not explained.

• What is a shipment? Is it a package?
• What is a ShippingCategory? Why I need one?
• What is a ShippingMethod? Do I need one?
• What is a ShipmentUnit?

[Zales0123]

Great catches! Any PR's fixing the mentioned issues would be more than welcome :) Regarding the explanation of these concepts, I totally agree they should be as clear as possible, we should take care about that. Thank you for such good ideas about how to improve our docs! 🥇

[cansozeri]

@Zales0123 The main problem in this project is the documentation, there is a great effort to programming but the documentation is weak. It could be hard to take a time to a learning curve because of a weak documentation. I hope you gonna improve the docs in the near future :)

[Zales0123]

Thank you for your opinion, @cansozeri :) I believe that the worst part of our documentation is Components & Bundles section, which is the most outdated and incomplete... On the other way, e.g. "The Book" or "The Cookbook" are kept in a relatively good condition.
The thing is, we, as a Core Team, have plenty of things to do with this project and documentation is not always our top priority (I know it's sometimes should). And that's why contributions from the community, especially to the documentation, are a huge help for us :) Moreover, I believe sometimes people outside of the Core Team have a better insight on where are the documentation weaknesses, as you use it more than us 😄

We will for sure try to fix documentation step by step, but we also strongly encourage you to contribute to it. Thanks! :)

[cansozeri]

@Zales0123 Thank you for your efforts, I have to understand what is going on in this shipment component and bundle first before to contribute to the docs :) I want to use it in my project but because of documentation I have to dig in the codes :) but I need time for it, if I can, I would be very happy to contribute to it ..

[Konafets]

I can second what @cansozeri wrote. To describe a behavior of f.e. the shipping component you have to understand it first. But if the documentation is wrong, the only thing someone can do is dive into the code and do trial and error. The problem here is: Writing a documentation from guessing does not help anybody.

@Zales0123 How about the idea to have a documentation hackathon or similar, where interested ppls from the community are in a room with the core team to discuss and document?

[lchrusciel]

@Konafets hackathon is a great idea, but there are several logistic problems. Where it should take place, when, who will pay for this, and how many people will join us :(

[stale[bot]]

This issue has been automatically marked as stale because it has not had any recent activity. It will be closed in a week if no further activity occurs. Thank you for your contributions.