Hello Sylius Community!
As you probably noticed we have recently started the amazing phase of projects’ stabilization, which will hopefully result in the release of Sylius 1.0 BETA in the foreseeable future. That important process in Sylius life comes up together with another important project – the documentation.
Some time ago we have merged the SyliusDocs repository into the main Sylius repository on Github. That action enabled us to have a better insight into the docs, but also to make the docs a bit more available to the community of Sylius’ contributors.
Let’s imagine that as a developer you encounter Sylius, Doctrine, Symfony or any other big project you know from the PHP world and you realize that these projects do not have even a single line of documentation. Therefore you do not know what are the requirements, how to install the project, how to use it, test it, customize and work with it on daily basis. You act as though you were blind in a giant, hazardous forest. There are no rules nor regulations, no reference, as a potential contributor you get lost and get discouraged quickly.
To overcome these problems we are using the documentation – where we can find solutions to many problems that we are facing everyday. Through docs we can share experiences in an organised, comprehensive and detailed way.
What is more in the open source projects like Sylius, where the contributors community is big and active, writing docs may become a way of understanding details of the project. Intensive peer review and discussions over the opened pull requests to the documentation may raise important issues, that are sometimes not visible while writing the code of some feature, but only when we focus on how it works while being described in the documenting process.
In order to organize our work we have developed a plan for the Sylius Documentation Content. You can find it here – feel free to discuss it under this issue.
We would like to focus on three important parts of the docs:
Describing the architecture of Sylius – with emphasis on describing the Resource Layer and the State Machines,
Documenting the concepts in Sylius – in order to show developers what tools and features are available and how to use them,
Cookbook and Customization Guide – to show how to make Sylius your very own system in an easy and comprehensive way.
We have assumed these are the cornerstones of Sylius that need to be described in its documentation. Having these we will be ready to release Sylius 1.0 BETA with certainty, that its users will be satisfied both with its code and the docs.
At Lakion we have internally started organising work with the documentation. The progress is yet visible – we have been polishing the major part of the Customization Guide. Also a lot of Concepts have been described already.
Right now we are preparing to investigate the needs for cookbook articles and define exact topics for the first set of them. We will be also iterating over the already written parts of the Book, which have to grow a little bit.
We have decided to conduct this process in an agile way – yes, we do have a scrum board, we have estimated tasks and divided them into 2-week sprints. That approach will hopefully help us increase efficiency.
And finally we have a huge request for you, dear Sylius community! Please, help us with the Sylius Documentation. Let it be perfect, with your support – even small – it will be much easier for us to satisfy everyone’s needs. Please head to our Docs Contributing Guide to learn more about the process of submitting patches to the docs.
Each and every pull request with the [Documentation] tag will be greatly appreciated and valued. We are also awaiting a helping hand with reviewing the emerging PRs.
Thank you in advance!
