[Documentation] Sylius 1.0 - The Documentation Plan

[CoderMaggie]

Hello Folks! 👋 👌 🙌

As we are currently approaching the final Sylius 1.0 BETA we have started thinking about upgrading our documentation. You've probably noticed a few emerging PRs to the Docs ( #5174, #5195, #5214 ) which are just a beginning of a whole big revolution.

We would love to develop understandable, well-organized, comprehensive documentation. To achieve that we will be needing strong assistance of the Sylius community. Every single PR with the [Documentation] tag will be appreciated a lot. :)

The Documentation Plan 📖

Together with @pjedrzejewski and @michalmarcinkowski we have sketched a detailed (but still initial) plan for the docs development.
The docs are divided into chapters and subchapters. Those which are for now the most important ones are marked with a 💥 .
We are presenting them as a checklist so that everyone will be able to see what has been already done, with a link to relevant PRs.

THE BOOK:

The Installation: 💥

• Requirements for running Sylius ( [Documentation] System requirements #5364 )
• Installing Sylius via Composer ( [Documentation] The Book - Installation #5174 )

System Architecture:

• Fullstack Symfony ( [Documentation] Architecture - Symfony, Doctrine & Twig #5420 )
• Doctrine & Twig ( [Documentation] Architecture - Symfony, Doctrine & Twig #5420 )
• Division into Components, Bundles, Platform ( [Documentation] Architecture - Divisions #5451 )
• Division into Core, Admin, Shop, Api ( [Documentation] Architecture - Divisions #5451 )
• Resource Layer 💥 ( [Documentation] Architecture - Resource Layer & State Machine #5489 )
• State Machine 💥 ( [Documentation] Architecture - Resource Layer & State Machine #5489 )
• Third Party Libraries: Payum, etc. ( [Documentation] Third party libraries #5500 )

Detailed concepts of Sylius:

• General: 💥
  Channels ( [Documentation] Concepts: Channels #5511 )
  Currencies ( [Documentation] Concepts: Currencies #5527 )
  Locales ( [Documentation] Concepts: Locales #5518 )
• Products, Variants and Options ( [Documentation] Concepts: Products #5581 )
• Taxons ( [Documentation] Concepts: Taxons #5630 )
• Attributes ( [Documentation] Concepts: Attributes #5608 )
• Order ( [Documentation] Concepts: Orders #5705 )
• Pricing
• Payments
• Shipments
• Checkout: ( [Documentation] Concepts: Checkout #5730 )
  Addressing
  Shipping
  Payment
  Summary
• Addresses: ( [Documentation] Concepts: Addresses #5920 )
  Countries
  Zones
• Inventory: ( [Documentation][Book] Inventory #6460 )
• Taxation: ( [Documentation] Concepts: Taxation #5962 )
  Categories
  Rates
  Zones
• Payments: ( [Documentation] Concepts: Payments #5816 )
  Methods
  State Machine
• Shipments: ( [Documentation] Concepts: Payments #5816 )
  Methods
  Categories
  Zones
  State Machine
• Promotions: ( [Documentation] Concepts: Promotions #5946 )
  Promotions
  Coupons
• Customers & ShopUsers: ( [Documentation] Concepts: Customer & ShopUser #5925 )
  Groups
• AdminUser : ( [Documentation] Concepts: AdminUser #5927 )
• E-mails
• Themes
• Fixtures: ( [Documentation][Book] Fixtures #6413 )
• Product Reviews ( [Documentation][Book] Product Reviews #6490 )
• Address Book ( [Documentation][Book] Address Book #6477 )
• Product Associations

THE CUSTOMIZATION GUIDE 💥 💥 💥 -> #5214

• Models
• Translations
• Forms
• Repositories
• Controllers
• Factories
• Validation
• State Machine
• Menu
• Integrating Templates
• Flashes

THE COOKBOOK

In this section we would like to have detailed HowTo articles. Like "How to change the user password validation?" or "How to configure Paypal?".

• How to add a custom model? ( [Documentation] Cookbook - How to add a custom Model? #6226 )
• How to configure Paypal Express Checkout? ( [Documentation] Cookbook - How to configure Paypal Express Checkout? #6250 )
• How to send a custom Email? ( [Documentation] Cookbook - How to send a custom email? #6194 )
• How to work with Sylius API?
• How to add custom fixtures?
• How to customize Sylius Checkout? ( [Documentation][Cookbook] How to customize Sylius Checkout? #6538 )
• How to resize images?
• How to configure Stripe for payments?
• How to render a menu of taxons?
• How to embed products?
• How to deploy to Platform.sh?

THE MIGRATION GUIDE

A section with migration instructions from specific platforms and general tips for custom shops migrating to Sylius. For example: How to write a product import command, how to write a command that gets products from different database connections, etc.

SYLIUS BUNDLES DOCUMENTATION

Document the most important bundles, especially the ResourceBundle, but bundles are not a priority. They should have working installation instructions before 1.0 BETA and that’s it. We will focus on their documentation after BETA release.

• GridBundle ( [Documentation][Bundles] SyliusGridBundle docs update #6312 )

SYLIUS COMPONENTS DOCUMENATION

Components are not a priority before 1.0 BETA, but should have up-to-date installation and usage instructions.

Final Thoughts 🏁

💚 Thanks guys for getting through this long issue. 💚
As the whole process has already started we are encouraging you to take part in it. Even just reviewing the docs will be a great help.

We are looking forward for your feedback!

The Sylius Team

[okwinza]

Hell, it's about time! 😋
I do have one suggestion tho: wouldn't it be nice to have "Migrating to Sylius" chapter aswell?

[pjedrzejewski]

@okwinza Definitely! We are migrating some stores from various platforms, so we could share some ideas and insights but I am really hoping that community will share more too. :)

[CoderMaggie]

@okwinza @pjedrzejewski should it be a subchapter of The Cookbook or an individual one?

[pjedrzejewski]

@TheMadeleine I think we could have a Migration Guide section with migration instructions from specific platforms and general tips for custom shops migrating to Sylius. For example: How to write a product import command, how to write a command that gets products from different database connection, etc.

That being said, it is quite ambitious to think about having all this migration stuff anytime soon, but hopefully more people migrate and someone finds time to write these docs. :)

[okwinza]

@TheMadeleine IMO it should be dedicated chapter since it's a more broad topic than "how to reset a password"

But some things can be extracted to the cookbook(like "How to create a User/[ResourceName] programmatically", etc) for sure.

[pjedrzejewski]

Ooups, missclick. 💃

[javiereguiluz]

In case it helps you, in the Symfony Docs we had a "Glossary" section since day one. The traffic it gets is residual and we're gonna remove it soon. I wouldn't waste any effort on that.

By the way, I agree with others about the migrating to Sylius docs. I can imagine for example a "Migrating from Magento to Sylius" article that provides not only technical advice and commands/code samples but also a brief explanation of the main conceptual differences between both platforms.

[pjedrzejewski]

@javiereguiluz Thanks for the feedback Javier, it helps a lot! @TheMadeleine It was my idea to add a glossary, but I agree we could skip that part. :)

[michalmarcinkowski]

@javiereguiluz good point! What is more, all from "Glossary" section will be described in "System Architecture" anyway.

[javiereguiluz]

Another thing I miss from the documentation plan (which by the way is great) is the "systems administration" part: how to deploy a Sylius project, migrate/upgrade between versions (e.g. database migrations), important things to monitor in a production Sylius project, a security checklist of things to double-check to make Sylius safe, etc.

[gabiudrescu]

a lot of the classes became final and all who ask about how to modify the behavior are pointed to decorating.

but I'd be interested in an example of how Sylius (team) would use this pattern when trying to achieve a goal such as "we need to change the behavior of this factory".

do you think this question deserves a page in the documentation?

[gabiudrescu]

also, I'd use the link as a RTFM for all further questions how "why is this class final, omg, how am I going to extend this" 🗡️

but that's only me being "friendly" 💃

[okwinza]

@gabiudrescu IMO it would be more useful to explain why these classes were made final and why you don't need to extend them in the first place.

[lchrusciel]

@okwinza AFAIR it was explained few times on Sylius issues.

Anyway, the question why these classes were made final and why you don't need to extendis a wrong question. The good one is why not?

We have to be aware that we have to maintain this code. Each public or protected method can cause a potential BC break. Final classes and private methods protect us from it and should be used wherever it is possible. With the interface we make a contract that the class which fulfill it will work correctly. We have also provided a sample implementation of them which resolves some problem. But not all of available cases.
I'm not an expert, so you don't have to trust me, but here you have some presentation about that. Here you have also some further reading about that.

I hope it clarify a little bit.

[gabiudrescu]

@okwinza that's also a good idea.

[CoderMaggie]

One important thing - "How to customize factories?" article comes to my mind :) And I must agree with @lchrusciel .

[pjedrzejewski]

@TheMadeleine +1 or maybe even generic article: How to customize Sylius services? Which explains how we do it on few examples, including the factory. WDYT?

[CoderMaggie]

It seems like the issue is... DONE! 🎉 🎉🎉

It took me some time to realise that all these ideas here are already covered! :D 💪

[gabiudrescu]

congrats @CoderMaggie for leading this effort.