I’ve got exciting news to share with you I’ve been working lately on improving our website / documentation infrastructure in order to make it simpler to keep docs up to date. This resulted in a reorganization of the website and changing the process too.
There are many improvements and here are some of the highlights:
- Documentation of all the gems have been moved to individual project repositories . Documentation source code lives in
docsitedirectories, ie you can find dry-validation documentation right here
- Documentation is now versioned in the sense that every
minorrelease will have its own version of documentation that we can keep up to date. You will notice that now all gem pages have version switchers .
- We now have
masterdocumentation on the website too. This should be useful if you’re living on the edge or for previewing docs for the upcoming features etc.
- Version-less URLs have been removed . If you go to a gem index page, like https://dry-rb.org/gems/dry-validation, you will be redirected to the latest version.
- We finally have clickable headers ie dry-validation#configuration-settings.
- The underlying middleman extension provides a nice set of admonition blocks. ie check out info block on the dry-schema index page.
- Internal links to documentation pages can be generated using extended markdown syntax, this should reduce the risk of having incorrect links.
- There are “Edit on GitHub” links on gem pages
- Last but not least - we have algolia-powered search !
Big thanks go to Svyatoslav Kryukov for helping with all those improvements
The new process
From now on, we have a new process when it comes to updating documentation. Because sources live in individual repositories, it is now possible to make updates to the docs along with PRs that add new features or make any API changes. This way we will always cover any change and a new release of a gem will automatically ship with a new set of docs.
When it comes to versioning, here’s how it works:
- Documentation for the next version of a gem should be updated in
- Updates to the existing documentation should be done in a
release-x.ybranch first, and then the release branch should be merged to
masterie if there’s an update to dry-validation 1.3 documentation in its
release-1.3branch, then these updates are merged to
masterso that the future release will include them too
- Projects and their versions are explicitly configured in the dry-rb.org projects.yml file. This is important to know because creating release branches or tags does not result in docs automatically showing up on the website. A new version must be added to this configuration file.
The downside is that multiple documentation versions may require applying the same change to multiple branches. ie if there’s
release-1.1 then it can happen that we have a fix that should be applied to both versions. Right now it’s a manual process but it will be automated at some point.
We’re more than happy to merge PRs with docs improvements. Every little fix counts, so please do not hesitate to push that new “Edit on GitHub” button and open a PR whenever you see a typo, a broken link or a missing piece of information that you happen to know
Furthermore, if you see any issues please report them.