Historically, the Magento User Guide has been published in three different editions to match the different Magento “flavors”.
User experience issues
In a web publishing environment, this duplication of content often has a negative impact around searching for the right content for the merchant’s needs. Across just the user guides for version 2.3, we had ~80% page duplication across the three editions, and ~95% page duplication across Commerce and Commerce with B2B.
From the feedback we receive, it is evident that merchants often end up in the “wrong” guide. This results in confusion about the features and fields described in our guides when it does not match the merchant’s own Admin environment.
Solution – a single, unified guide
We are pleased to announce our transition to a unified user guide for Magento 2.3. This new publishing model provides:
- Improved SEO and Google searchability to get users to exactly the information they need by eliminating page and content duplication
- Improved visibility of Commerce and B2B features vs. Open Source features
This new guide uses design elements throughout to identify features and functions that are edition specific, or that require the B2B feature set.
We are also using a new simplified URL path: docs.magento.com/user-guide/
Improved contributor experience
We are committed to an open contribution model for the Magento User Guide. Our initial Jekyll publishing framework, which was designed to produce three separate guides from a single set of source files, came with added baggage of condition coding and multiple sets of .yml files to define the variances between the guides. This transition to a unified user guide improves the contributor experience in many ways:
- A simplified framework, with a single set of .yml files to define our web information architecture
- Removal of conditional statements in content – simplified source files
- Support for simple Liquid tags to denote content that is specific to one of the Magento editions or the B2B module: {:.ce-only}, {:.ee-only}, and {:.b2b-only}
- Support for an Edition parameter in the .yml front matter for whole pages that are edition-specific
- Simplified Rake tasks that can support a local config file
- Reduced build and testing times
- All pages are included in the build
If you ever have questions about authoring user guide content, get in touch with us on Slack in the #merchdocs channel and we will help you out.
Stay in touch! Say hello to the Magento Docs team on Twitter at @magentodevdocs.