After finding some flaws in the way we structured things, we reconfigured our Documentation section with URLs better matching 'traditional permalinks.' This blog post talks about our changes, and how and why this benefits everybody.
The Issue
We generate much of our documentation for the Portal automatically. It comes from sources internal to the company, but external to the Portal, itself. Arranging it in a specific way presented a challenge, initially solved by scripting an ordered menu (basically a key-value pair of the order and the page). This wound up bodged onto the name of the document as the URL for the page.
Here’s an example:
https://developers.yonomi.com/docs/platform/util-traits/08-traits-overview/
That worked fine, initially. It went sideways on us as our pool of documentation grew. Take the following example:
https://developers.yonomi.com/docs/platform/util-traits/09-traits-overview/
If (When) a menu item goes into rotation above the Traits Overview, that requires a change anywhere anyone hard-coded it as item number eight. If anyone referenced that page directly, how would they know if the old one didn’t automatically redirect the client?
Unsustainable practice identified: how do we fix it?
Hugo configuration and front-matter to the rescue!
The Change
Using Hugo as we do, it was - fortunately - a relatively straightforward fix: update the configuration to use title-based permalinks and add both “weights” and aliases to the front-matter of the generated documents. This shift should produce URLs in a much more friendly and familiar fashion. It also allows us to use the same key-value list approach without worries of polluting the URL.
Riffing on the earlier example, the Traits Overview document now looks like this:
https://developers.yonomi.com/docs/traits-overview/
Easier to parse, by a human or a robot; referenced externally in a sustainable way; and generally just a lot cleaner.
While the initial push of finding and adding any necessary aliases was a bit of extra work, it shouldn’t present an ongoing struggle.
We always welcome feedback! Tap the button at the top of the page.
The Outcome
We aim to constantly improve the experience on the Developer Portal, and that starts with having the information readily available (and not producing errors). We hope this change is a good step in that direction, and ask our users’ forgiveness for any inconvenience caused by the shifting URLs.
The change should make navigating the Portal simpler, overall: documentation lives at the ./docs endpoint, and “sane guesses” should now score on documents with the guessed title (“How do I list devices? Hmm… /docs/listing-devices? Bingo!).
This change should make engaging with the Developer Portal documentation more sane and predictable. Thanks for reading!
Notes
- Hugo is a Go-based platform which uses Markdown to generate fast, high-quality static sites.