[Documentation] Sylius 1.0 - The Documentation Plan #5275

Open
TheMadeleine opened this Issue Jun 16, 2016 · 24 comments

Projects

None yet

10 participants

@TheMadeleine
Contributor
TheMadeleine commented Jun 16, 2016 edited

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 ( #5364 )
  • Installing Sylius via Composer ( #5174 )
  • Installing Sylius via package

System Architecture:

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

Detailed concepts of Sylius:

  • General: 💥
    Channels ( #5511 )
    Currencies ( #5527 )
    Locales ( #5518 )
  • Products, Variants and Options ( #5581 )
  • Taxons ( #5630 )
  • Attributes ( #5608 )
  • Order ( #5705 )
  • Pricing
  • Payments
  • Shipments
  • Checkout: ( #5730 )
    Addressing
    Shipping
    Payment
    Summary
  • Addresses: ( #5920 )
    Countries
    Zones
  • Inventory: ( #6460 )
  • Taxation: ( #5962 )
    Categories
    Rates
    Zones
  • Payments: ( #5816 )
    Methods
    State Machine
  • Shipments: ( #5816 )
    Methods
    Categories
    Zones
    State Machine
  • Promotions: ( #5946 )
    Promotions
    Coupons
  • Customers & ShopUsers: ( #5925 )
    Groups
  • AdminUser : ( #5927 )
  • E-mails
  • Themes
  • Fixtures: ( #6413 )
  • Product Reviews ( #6490 )
  • 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? ( #6226 )
  • How to configure Paypal Express Checkout? ( #6250 )
  • How to send a custom Email? ( #6194 )
  • How to work with Sylius API?
  • How to add custom fixtures?
  • 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.

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
Contributor
okwinza commented Jun 16, 2016

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

@pjedrzejewski
Member
pjedrzejewski commented Jun 16, 2016 edited

@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. :)

@TheMadeleine
Contributor

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

@pjedrzejewski
Member

@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
Contributor
okwinza commented Jun 16, 2016

@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 pjedrzejewski reopened this Jun 16, 2016
@pjedrzejewski
Member

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
Member

@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
Member

@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" ?

@TheMadeleine
Contributor

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
bnd170 commented Sep 9, 2016

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
Contributor

@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
Contributor
lchrusciel commented Sep 9, 2016 edited

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
bnd170 commented Sep 9, 2016 edited

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
Contributor

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
Contributor

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
Contributor
okwinza commented Oct 25, 2016

@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
Contributor

@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
Contributor

@okwinza that's also a good idea.

@TheMadeleine
Contributor

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

@pjedrzejewski
Member

@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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment