Hermes Guide: versioning

[adizere]

Summary

The guide we keep at hermes.informal.systems is pretty amazing.

For easier maintenance, some ideas for future work include:

• modify the ci action to unpin from the dev branch (Add a bit more context to the What is Hermes section of the guide #610)

https://github.com/informalsystems/ibc-rs/blob/5dc062707b2f5f34722e203f26b74658646b76c0/.github/workflows/guide.yml#L3-L6

• include a versioning scheme, so we can access a specific version of the guide, for example

hermes.informal.systems/v1/
hermes.informal.systems/v2/

Note that the current versioning scheme is very crude and it's just a remark in the guide readme file.

• design a staging area, so that we're keeping multiple instances of the guide online: one that reflects whatever is in the master (e.g., via uri hermes.informal.systems/master/), and the other versions for all published (tagged) versions. It would be amazing if we can automate the tagging process to deploy new versions out of master.

• run the guide build job against two chains, and use something like termbook to automatically insert the results of the various commands instead of having to maintain those manually.

---

For Admin Use

• Not duplicate issue
• Appropriate labels applied
• Appropriate milestone (priority) applied
• Appropriate contributors tagged
• Contributor assigned/self-assigned

[romac]

modify the ci action to unpin from the dev branch

#610

[andynog]

Did some preliminary investigation on how to support versioning with mdbook. There might be a few options.

Is the idea to have some sort of a drop down box on the documentation site so users can switch between versions (something similar to cargo docs site) ?

[romac]

That would be nice feature to have but it's not mandatory imho.

…

On 4 Feb 2021, at 22:32, Andy Nogueira ***@***.***> wrote: Did some preliminary investigation on how to support versioning with mdbook. There might be a few options. Is the idea to have some sort of a drop down box on the documentation site so users can switch between versions (something similar to cargo docs site) ? — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#609 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAA2CYK5LUXRDO4NMNH2YEDS5MHAXANCNFSM4XDFMZWA>.

[andynog]

I think supporting that will be too complex at the moment with mdBook, probably would need to create a pre-processor or add-in to support that. The easiest way is to have maybe separate jobs in CI (like one to publish the guide when master is changed and push to gh-pages branch) and other that pushes the staging to another place so we can test the updates to documentation on a different place.

[adizere]

Beside versioning, I found this principled approach to doing documentation: https://documentation.divio.com.
Would be good if we try to apply some of the ideas in there, in particular these dimensions