Improved documentation and the new process

Announcements
1

Hey!

I’ve got exciting news to share with you :smile: 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.

Improvements

There are many improvements and here are some of the highlights:

  1. Documentation of all the gems have been moved to individual project repositories . Documentation source code lives in docsite directories, ie you can find dry-validation documentation right here
  2. Documentation is now versioned in the sense that every major and minor release 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 .
  3. We now have master documentation on the website too. This should be useful if you’re living on the edge or for previewing docs for the upcoming features etc.
  4. 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.

Also:

  1. We finally have clickable headers :sweat_smile: ie dry-validation#configuration-settings.
  2. The underlying middleman extension provides a nice set of admonition blocks. ie check out info block on the dry-schema index page.
  3. Internal links to documentation pages can be generated using extended markdown syntax, this should reduce the risk of having incorrect links.
  4. There are “Edit on GitHub” links on gem pages :tada:
  5. Last but not least - we have algolia-powered search ! :mag_right: :confetti_ball:

Big thanks go to Svyatoslav Kryukov for helping with all those improvements :heart:

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:

  1. Documentation for the next version of a gem should be updated in master branch
  2. Updates to the existing documentation should be done in a release-x.y branch first, and then the release branch should be merged to master ie if there’s an update to dry-validation 1.3 documentation in its release-1.3 branch, then these updates are merged to master so that the future release will include them too
  3. 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.0 and 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.

Please help!

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 :smile:

Furthermore, if you see any issues please report them.

Cheers!

P.

4 Likes
3

These changes are a massive improvement. Thank you so much for pioneering this effort! I would love to see the same thing happen in the rom-rb family as well.

One thing we should take care to do is properly configure SEO for the versioned pages. We should always strive to have the latest documentation show up in Google, or else it can lead to a really confusing UX for devs. Potentially we can configure the robots.txt to noindex the versioned pages? We should take care to make sure that searching for docs in google Just Works.

Great work @solnic and @skryukov for these changes!

2 Likes
4

I have very little experience in SEO so any help here would be highly appreciated :sweat_smile:

5

the two main things:

  1. instruct crawlers not to crawl individual versions, and only have then crawl latest documentation. here is how react does it

  2. if generate a sitemap.xml of all the pages we want indexed and submit to https://search.google.com/search-console/about

1 Like
6

thank you @ianks - I reported an issue where I’m making a todo list with SEO improvements, starting with the two items you mentioned.