The Docs team here at Magento works diligently to provide documentation for all new features going out the door, chronicle it all in our release notes and What’s New topics, and update existing docs that need more context---all with the goal of improving user experience.
Alongside that feature development-centric work, we are also constantly maintaining and improving the infrastructure and usability of our documentation sites. Some of this work goes widely unseen, but we have added new site features and implemented process enhancements that are helpful to our users and doc contributors.
Last edited date
Now, it’s easy to see exactly when a topic was last edited. We added a last edited date feature to our DevDocs site that shows you exactly how long ago it was revised.
Click the X days ago text to get more detail. Never again question whether a topic could use a refresh (and if it does, click Edit this page on GitHub and you’re off to the races)!
Site switcher
Remembering URLs is hard. Adding bookmarks to your browser is helpful, but who has time for that?! Switching between our docs sites is now easier than ever with the addition of our new site switcher.
Click the grid icon in the top right-hand corner of any docs site and click the site you want to navigate to. That’s it!
Auto-generated content
Did you know we have a slew of docs content that is actually auto-generated? Auto-generating a portion of our docs content allows us to be more efficient with our time so we can work on complicated technical tutorials, information architecture advancements, and other pressing doc tasks that arise during the fast-paced software development process.
Our Module Reference Guides, Backward Incompatible Changes Reference, and any files in the /data directory are all auto-generated and published in each release cycle.
Cloud docs always current
Tired of reading a whole Cloud topic only to realize you’re reading info for a Magento version not applicable to you? We hear you, and we have a fix for that. Our Cloud documentation is now applicable to the current version of Magento---always!
When we need to, we bring attention to specific Magento version information via inline text right in the documentation. It’s rare that we need to do this, but when we do you won't miss it!
That’s right---Once you navigate to our Cloud docs you can read away, unhindered by version concerns. This simple change removes a layer of uncertainty and ensures you can get to the content you need quickly.
Version tags
Our published docs sites, like devdocs.magento.com, include documentation for supported versions of Magento. Sometimes, though, you may need to see the docs at a certain point in time, or a certain version in time.
Enter version tags! Within GitHub in one of our docs repos, you can see everything in the source at a version point in time. Click the Tags tab in the Branches menu in our repo to select the version for which you want to see the repo and docs.
You can also checkout the repo and its docs locally for a specific version point in time. Check out the Building old versions section of our GitHub wiki to learn how.
Build locally with Jekyll
When contributing to our repos, such as DevDocs, MerchDocs, PWA Docs, etc., sometimes it’s helpful to actually see the changes you are iterating. This provides a layer of quality control before your pull request ever reaches our repo and the reviewing eyes of the Docs team.
You don’t need a fancy or complicated setup to serve the site locally for previewing purposes. With the magic of Jekyll and Ruby you can easily spin up a generated website that auto-refreshes with your changes as you make them!
See the Building this site section of our GitHub wiki to get started. Having trouble building the site? Get in touch with us on Slack in the #DevDocs channel and we will help you out.
Stay in touch! Say hello to the DevDocs team on Twitter at @magentodevdocs or in the Community Engineering #devdocs Slack channel.