Sylius: Documentation tone of voice debate

[gabiudrescu]

Sylius docs version: in general, all documentation

Description
Started from this: https://twitter.com/mpzalewski/status/1024911176138993664

The main idea is that documentation such this one often stop right when it starts to be really useful.

It helps you understand how a plugin is structured, what do you need to modify an entity or to create a new one, but when it comes to actually using it in frontend or admin or whatever other part of the app that is used by the business, it leaves it to the developer to figure it out.

and from my experience, this hurts Sylius very much, from the user perspective. because a very good codebase is often misused by the developers who are left without a hint on how to use that model in a twig or an API.

yet another good example of this (bad) practice: https://docs.sylius.com/en/1.1/components_and_bundles/bundles/SyliusResourceBundle/index.html

SyliusResource, imho, it's one of the best ideas I've encountered in the Symfony community, but this specific documentation is focused on what bits and pieces of this bundle can do, separately one from each other, not glued together, as a whole.

My approach on these docs would be from "I need to solve this specific business need and so I'm going to use this specific library" rather than "I have this awesome library, let me show you what it can do / what methods you have available and you figure it out how to use these to get what you need".

The biggest problem is that sometimes you don't know what you need and end up using the wrong tools :-(

PS: hope you won't perceive this as too harsh. it's not my intention to bash Sylius in anyway.

[alexrowesoap]

I'd second the sentiment that Sylius is a great platform, and one that I really _really_ hope kills off the big orange M. It's a pleasure to work with.
I do have to also agree about the documentation. For me, as a developer, the tone is fine but the lack of context is an absolute killer.

A good example from last night: The docs on the sylius.order.post_complete event (https://docs.sylius.com/en/1.2/book/orders/checkout.html).
An event is triggered. Great! How do I get the order out of said event?? (its $order = $event->getSubject();). For newer devs, there's also no hints on how to catch said event ( in your service file add

tags:
            - { name: kernel.event_listener, event: sylius.order.post_complete, method: onOrderCreated }

to your service).

Another example is when we picked Sylius, it said it supported Sagepay via the payum-omnipay bridge.
We spent _ages_ trying to get this running because that's what the docs at the time said to do. As it transpires, it's virtually impossible, the references have been removed iirc, and I've yet to hear of anyone pulling it off.
Further, the docs on setting up gateways don't include anything on how to setup, display or save options in the backend of Sylius.
A proper skeleton sylius-payum gateway bundle that works in both the front and backend would have been invaluable.

The only other issue regarding documentations is more of a legacy one.
Several of the older repos (SyliusRbacBundle as an example) just have the stock readme, and refer back to docs.sylius.org but the docs for these older repos don't exist any more.
IMHO the readme should at least contain installation and usage instructions specific to the repo.
I can tell you as an ex-mage dev, lots of repos and SO posts linked to their docs and forums. When they changed the forum URLs and the doc URLs these links became worse than useless as they just polluted the search results.
I would like for this not to happen to Sylius, and the simplest way is to have at least _some_ documentation bespoke to the repo in the readme.

If the docs could just be tided up and expanded, it would make adopting the platform more straight-forward.

[vvasiloi]

@alexrowesoap Sylius is build on top of Symfony and other libraries, like Payum for payment integration, so you have to be familiar with those too. For anyone who worked with Symfony it's obvious how to work with events. Also, if you read the documentation of Payum, it will be clear how to handle gateway config.
I'm sure there are references to the docs of the libraries Sylius uses and I don't see the point of copying those to Sylius docs.
For events: https://docs.sylius.com/en/1.2/book/architecture/events.html
For payments: https://docs.sylius.com/en/1.2/book/orders/payments.html

[alexrowesoap]

In regards to the events, I know how events work: I'm giving an example where the docuemtnation doesnt yeild context to someone starting out. There is, as you say, a page regarding events but why then isnt it linked to form the event listing on the checkout documentation page? It's small things like that that are the issue.

[psihius]

@vvasiloi the issue is people are coming to an e-commerce solution and not to a Symfony framework.
This is not a library, so a lot of people who hop on have never worked with Symfony. And even if you worked with Symfony - no everything is obvious and some things are just downright confusing.
Making a Payum lib (as I have done 3 of them) for payments is an absolute nightmare and time sink. Payum's docs are not good, the lib itself internally is not that great and coupling it all together with Sylius on top is something that even a very experienced dev should not take lightly.

[gabiudrescu]

let's bring others into this discussion too:

• https://github.com/odiseoteam/SyliusVendorPlugin

This plugin sounds like an awesome addition to Sylius. but unfortunately, it's far from what I have imagined when I read the repo title.

When I think about Vendors in an eCommerce context, I imagine that a vendor is a supplier of a product and when products are created on the website, they get stock from a purchase order sent to the vendor and approved by them.

I think about shipping pallets of merchandise that are received by a warehouse, that creates several other objects that translate in the end in an integer value on ProductVariant on_hand property.

what do I get with this plugin?

an entity with no behavior (very skinny model), a form, a menu, a (basic repository) and a fixture.

what can I do, from the business point of view, with this plugin?

pick a vendor name, email, address, upload a picture for that vendor, a description and... that's it. how can I, as a business, make money out of this?

will I be able, as a business owner, to define how vendors affect my shop behavior if I install this plugin? no - not without coding on top of this plugin.

---

bottom line is that I have high expectancy from a plugin by just reading the name, when in reality, after diving into code.. things are far far away in the future, after much effort from my part.

the goal of this conversation is to raise awareness about the approach on plugins, documentation and, why not, even Sylius core development oriented to solve a real business itch.

I don't say that the current components don't, but it's not that obvious from the beginning how to use them to solve which itch.

[vvasiloi]

@psihius Doesn't Sylius possition itself as an eCommerce Framework and not a "solution"?
For example, the checkout documentation page mentioned by @alexrowesoap uses a lot of 3rd party elements and including documentation or even references for all of them will be exaggerated IMHO.
Reading the Introduction and Architecture sections from The Book gives an overview of how Sylius works. Then one can find more details in the tematic sections.
My point is that giving full/more context might be more confusing that helpful, because often it will be an overwhelming amount of information.
I agree with @gabiudrescu that docs in form of how-tos would be more helpful, like in The Cookbook.

[gabiudrescu]

another plugin to debate:

• https://github.com/BitBagCommerce/SyliusShippingExportPlugin from my good friend @bitbager

the idea is great and I can see that this plugin is solving a real business problem. but I can see this because I know the context and I have tried it myself, not because it's explain in plain English in its docs or its readme.

imagine you have 10k € to start an eCommerce business that is choosing Sylius as its platform. you pay 2k € for a full stack developer to customize your look and feel and invest the rest of 8k € in stocks. I'm mentioning these amounts to make a point we're talking about a bootstrapped small business enterprise.

one month later, you reach the level of 10 orders a day and you realize that you cannot manually create shipping notes in the courier interface and you decide you want to automate this process by integrating Sylius with the courier API.

you'll be smart and research the plugin's marketplace and you reach this repo on github. you read the description and become very excited about it.

then you call the full stack developer and tell him that you need a button that generates the shipping notes for orders when they are ready to be shipped and those notes need to be synced via API with the courier.

you also tell him that you found a plugin that does just that and he just needs to install it. the developer is sloppy and decides to take your word on this and estimates it will require him no more than 1 or 2h to do so.

after the installation of the plugin, the developer realizes that the only thing extra brought by the plugin is:

• CRUD for 2 skinny models (shipping gateway and shipping export)
• some configurations that make this CRUD available in the admin context

what can I do with this for my business? well.. pretty much nothing.

questions I might have as a business owner:

• will this plugin automatically generate the shipping papers on my behalf?
• are they going to be synced with the courier system?
• am I able to see what the courier has received from my system?
• what happens if the customer change its mind about the delivery address and I need to issue another shipping paper? can I do that? what happens with the old one if I generate another one

technically, the answer is yes, you can do all of the above with the plugin developed by BitBag... but it would require some effort on developing all that.

some effort could range from a couple of days to a couple of weeks or even months, depending on your business case, sylius / symfony knowhow and api complexity.

and that's how you turn a 1-2h estimation of a plugin installation to a big project of tens or even hundred of hours of programming effort.

---

my pledge is to shift our mindset from "let's build this awesome something that can do everything but as is it does pretty much nothing" to "let's build this awesome something that solves this specific itch but if required, it can do pretty much everything, because it's flexible and it's not tightly coupled and it's well engineered'.

PS: @bitbager a quick fix to the readme of this plugin would be, in my opinion, to reference it to this other plugin and tell potential users that after installing the first one, they need to provide another plugin that actually does the implementation of an API, otherwise, there won't be much business value for them out of the box.

[bitbager]

Hello chaps!

Here are a few words from me. I think that after doing a plugin or two, we have some experience in this area.

The great thing about Sylius is that it was built by developers for developers. It makes it a great platform to work with, which is highly flexible. However, eCommerce is not just about development. As Sylius is starting to become a serious business tool, there's no longer place for a documentation similar to Symfony bundle. We spent thousands of hours learning Sylius, however, most of the knowledge we gained about this platform didn't come from the documentation. The most core understanding we have came from reading & debugging the core code. We read almost all lines of code, debug all services and puzzling it to the business needs. At this stage, we probably know about Sylius even more than we are able to use as a company. Personally, I find it great and because I love to be a geek and it wasn't a problem for me at all. However, not everyone is a geek. I think that there are plenty of people, who could have decided to use Sylius but they didn't because they didn't realize how great it is from the documentation. I would risk a few bucks to say that not many people research the whole codebase to decide if the solution fits their needs. The docs are awesome, really (especially compared to Magento, like the whole Sylius 😄), but they are great only for the developer. And because the decision about the technical stack in middle and big size business is not always made by a developer, rather a CTO or CEO. IMHO what's missing from docs is the reason part. There is always a purpose we work with some code. It would be worth not to forget this purpose.

The other concern I also have about docs is that there is a lot of great code in the Sylius community, which we cannot use because we don't actually know how. Once again, ResourceBundle, ShopApiPlugin are only a few examples.

I would shoot in my own feet mentioning payments (Payum) documentation. Currently, at BitBag we often integrate a lot of payment gateways for enterprise clients just because they don't know how to do it. I know that I was supposed to write the docs, sorry for that @CoderMaggie, however, I think that someone finally has to take the responsibility for this. Chances are that we won't always be a custom Sylius payment plugin development company 😄

I think that Pimcore's documentation might be a great role model, especially for Sylius. Sylius & Pimcore are quite similar from the business perspective - they mix UI & development, are flexible, not to mention they are both Open Source & Symfony based platforms. The main difference between these two platforms is that Pimcore is far more business advanced than Sylius is, being a great dev oriented platform at the same time.

CC: @CoderMaggie, @Zales0123, @pjedrzejewski

@gabiudrescu, I will update the plugin documentation. Thank you for the feedback. As you can see, ae ain't better at documentation, however, this specific plugin is our only generic, Payum inspired extension. Rest of BitBagCommerce's organization plugins are actually more business specific and we try to explain the business reason behind they existence in README.

[jakilcz]

The docs for sylius are ok but it's hard to tell for whom they are aimed. Part of it looks like it's for total amateurs, and part of it is for people who are familiar with symfony. It's quite confusing, and makes entry point quite complicated.

One of basic things to start - custom model:
https://docs.sylius.com/en/1.2/cookbook/entities/custom-model.html
Shows how to do it with outdated SensioGeneratorBundle that won't work with symfony 4.

And even this sentence:
Remember to have the SensioGeneratorBundle imported in the AppKernel, as it is not there by default.
Obvious if you have some experience, really confusing if you have none. Puttin example how to add it there, would take 3 minutes.

https://docs.sylius.com/en/1.2/customization/menu.html
example in point 1 adds submenu, but not real links to any place, quite useless. (And i'm not even sure it's working, i had to find solution how to add links in some other place.)

https://docs.sylius.com/en/1.2/book/orders/payments.html

Payment methods - not sure why we'd like to set paymetn methods programatically when it can be set in admin panel.

"You’ll probably need also this kind of configuration in your app/config/config.yml for the gateway’s factory:"

"You'll probably" sounds like - we think it can be needed, but we're not sure... Should be precese - "you need it if..."

And there are many other places like that, that are confusing, not up to date or just wrong. You will not become popular if docs will block newcomers. Symfony has great docs and it's for sure part of their success. I know nooone likes to work on docs, but it's just necessity and should be done after any change of feature.

[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.

[alexrowesoap]

Thanks @Zales0123