Sylius: [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: 💥

• [x] Requirements for running Sylius ( #5364 )

• [x] Installing Sylius via Composer ( #5174 )

  System Architecture:

• [x] Fullstack Symfony ( #5420 )

• [x] Doctrine & Twig ( #5420 )
• [x] Division into Components, Bundles, Platform ( #5451 )
• [x] Division into Core, Admin, Shop, Api ( #5451 )
• [x] Resource Layer 💥 ( #5489 )
• [x] State Machine 💥 ( #5489 )

• [x] Third Party Libraries: Payum, etc. ( #5500 )

  Detailed concepts of Sylius:

• [x] General: 💥
  Channels ( #5511 )
  Currencies ( #5527 )
  Locales ( #5518 )

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

• [x] Product Associations

  THE CUSTOMIZATION GUIDE 💥 💥 💥 -> #5214

• [x] Models

• [x] Translations
• [x] Forms
• [x] Repositories
• [x] Controllers
• [x] Factories
• [x] Validation
• [x] State Machine
• [x] Menu
• [x] Integrating Templates
• [x] 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?".

• [X] How to add a custom model? ( #6226 )
• [X] How to configure Paypal Express Checkout? ( #6250 )
• [X] How to send a custom Email? ( #6194 )
• [x] How to work with Sylius API?
• [x] How to add custom fixtures?
• [x] How to customize Sylius Checkout? ( #6538 )
• [x] How to resize images?
• [x] How to configure Stripe for payments?
• [x] How to render a menu of taxons?
• [x] How to embed products?
• [x] 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.

• [X] GridBundle ( #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! :yum:
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.

[ylastapis]

Hi @TheMadeleine and congratz. It's a tough work but definitely essential.

What about the API part ? Have you planned to remove it or is it all summed up into "Division into Core, Admin, Shop, Api" ?

[CoderMaggie]

Hello @ylastapis ! Thanks :)

The API part is currently covered by the "API Guide" see -> http://docs.sylius.org/en/latest/api/index.html . Do you have any questions or suggestions to that part?

[ylastapis]

Keeping it apart is a good thing, I was just wondering cause you don't mention it in the documentation plan above :)

Currently API documentation is segmented in "Resources" and for each one:
The endpoint / The required & optional parameters / status code when ok / example response

• Why not something more like
  Endpoint / required & optional parameters / all status codes (and not only the 200|201)
  obviously, 400, 401, 403 will be generic, but I'm talking about the custom ones, if any.
  IMO we don't need the response part, it's more source of confusion than helpful (and hard to maintain !) I prefer check with postman to see what's happening :)
• Also, having a full example on how to process a full course through API (creating a customer, displaying product list, displaying a product, creating a cart, adding product to cart, going to checkout, filling billing & shipping, get shipping methods, selecting shipping method, get payment methods, selecting payment method, review order, place order, process to payment).

@TheMadeleine wdyt ?

[bnd170]

As a user of Sylius I have to say that the current documentation is quite short, often it is insufficient.

It would be an objective to evaluate, documenting the extensible part of the project with examples on how to create new features.

I have seen limited with the current documentation when creating a simple blog. I have had many doubts when, for example, create a custom repository of an entity or change the way the administration listings shown.

Maybe a little Guide about creating new features would be nice.

[Zales0123]

@bnd170 For now we're trying to make documentation usable at all ;) @TheMadeleine is doing her best to cover all _Sylius_ features until stable release. Of course, there are many things that can be improved and described longer and with more details, but we must be pragmatic if we want to develop good documentation that can be easily extended and improved. Nevertheless, thank you very much for your comments, there is always good to have any feedback from community 🏇

[lchrusciel]

We always try to do our best to answer questions here or on stackoverflow. We are preparing a Slack channel to improve communication in a community. But we have limited resources also. So feel free to help us with documentation each time you resolved one of your problems. We would really appreciate any help. 🆘

[bnd170]

Do not take my words as criticism.

I will begin to collaborate with the project when I have more experience with it, I am delighted with Sylius and greatly appreciate the work you do.

I hope that within not too long may help to improve both documentation and code of Sylius :)

Btw: The Slack channel seems an awesome idea 👍

[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" :dagger:

but that's only me being "friendly" :dancer:

[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! 🎉 :tada::tada:

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

[gabiudrescu]

congrats @CoderMaggie for leading this effort.