Skip to content

Latest commit

 

History

History
252 lines (182 loc) · 7.81 KB

versioning-documentation.md

File metadata and controls

252 lines (182 loc) · 7.81 KB
cSpell:ignore
Batard Brubaker Pursley velero fullversion githubbranch docsbranch Tanzu Rosland Horgan Takahashi

Technical Documentation Versioning with Hugo & Netlify

Technical Documents Versioning is an intersection of:

Changes + Language + Navigation + Search

For small to medium sized sites using one language/location, a folder based method is likely the best method to balance these considerations.

Things discussed in this article:

  • Things to consider when thinking about versioning documentation
  • 2 viable schemes available (for Hugo/Netlify)
  • Dropdown menu navigation code examples
  • Trade offs

Versioning Considerations

What are the main concerns when versioning technical documentation in a website?

Readers

  • Ease of navigation/understanding

Maintainers / Writers

  • How hard is it to update when it's time to cut a new version?

Necessity

  • Does the documentation need versioning yet?
  • YAGNI (You aren't gonna need it - Don't implement things before you actually need them)

Navigation

  • Differences between versions (how do you deal with pages that have been added, removed, or moved between releases?)

Searchability

  • Does the duplication of pages affect search results? How do you manage result priority between versions?

Localization / Internationalization

  • How does the added complexity of language/locale versions affect the version system?

Compartmentalization

  • Does all of the site need to be versioned?
  • How do we avoid versioning the entire site if only Documentation versions are the goal?

Versioning Schemes

For a Hugo / Netlify setup:

friendly schemes unfriendly schemes
None (don't version)
Folder based Query Strings
Subdomain based Cookies

Because Hugo is a static site generator, and Netlify abstracts a lot of the server away Query Strings and Cookies don't really work for a Hugo / Netlify site.

Folder based

Folder based

Each version of the documentation is placed in its own folder. This is probably the easiest way to start versioning.

content
└── docs
    ├── _index.md
    ├── v1
    ├── v2.2
    │   ⋮
    └── v3.4.0

Scores high on: - Maintainer ease of updates - Compartmentalization Scores low on: - Localization / Internationalization

Folder based navigation code example

The folder based method of versioning can make the website code more complex.

One of the things that make this an interesting example is how Batard (2020, L8-L18)1 manages the navigation in the /site/layouts/docs/versions.html file, particularly the use of the replace function to ensure that when the links in the dropdown menu are built, the versioned links reflect the currently loaded page:

velero.io /site/layouts/docs/versions.html

<div class="dropdown-menu" aria-labelledby="dropdownMenuButton">
  {{ $original_version := printf "/%s/" .CurrentSection.Params.version }} {{
  $latest_url := replace .Params.url .CurrentSection.Params.version
  .Site.Params.latest | relURL }} {{ $currentUrl := .Permalink }} {{ range
  .Site.Params.versions }} {{ $new_version := printf "/%s/" . }}
  <a
    class="dropdown-item"
    href="{{ replace $currentUrl $original_version $new_version | relURL }}"
    >{{ . }}</a
  >
  {{ end }}
</div>

Batard (2020, L8-L18)1

Folder based versioning can make site configuration less complex.

velero.io velero/site/config.yaml

  versioning: true
  latest: v1.5
  versions:
    - main
    - v1.5
    - v1.4
    - v1.3.2
    ⋮

Brubaker et al. (2020, L14-L20)2

Subdomain based

The subdomain scheme uses some simpler template code to generate links, only having to update the .url, but the Hugo config file is made more complex.

Subdomain based

Each version of the documentation is its own site

  • Uses git feature branches rather than folders to organize versions
  • Separate site in Netlify for each version supported
  • Simpler template code, more complex config

Scores high on:

  • Localization / Internationalization Scores low on:
  • Compartmentalization
  • Maintenance, each version is its own site

Subdomain based navigation code example

Same style of dropdown function as above, but made simpler because of the configuration: https://github.com/kubernetes/website/blob/main/layouts/partials/navbar-version-selector.html

<div
  class="dropdown-menu dropdown-menu-right"
  aria-labelledby="navbarDropdownMenuLink"
>
  {{ $p := . }} {{ range .Site.Params.versions }}
  <a class="dropdown-item" href="{{ .url }}{{ $p.RelPermalink }}"
    >{{ .version }}</a
  >
  {{ end }}
</div>

Pursley et al. (2020, L4-L9)3

The dropdown example is made simpler because the config is more complex and because the server setup is more complex.

https://github.com/kubernetes/website/blob/main/hugo.toml

[[params.versions]]
fullversion = "v1.20.0"
version = "v1.20"
githubbranch = "v1.20.0"
docsbranch = "master"
url = "https://kubernetes.io"

[[params.versions]]
fullversion = "v1.19.4"
version = "v1.19"
githubbranch = "v1.19.4"
docsbranch = "release-1.19"
url = "https://v1-19.docs.kubernetes.io"

Bannister et al. (2020, L180-L192)4

Summary

Version using folders if:

  • maintainer ease of updates is a priority
  • localization / internationalization not a priority
  • it is important that only the documentation is versioned (and not, for instance, the blog)

Version using subdomains if:

  • localization / internationality is planned
  • compartmentalization not a priority

For small to medium sized sites using one language/location, a folder based method is likely the best method to balance versioning considerations.

References / Credits

This page has been adapted from the Technical Documentation Versioning slide show, its source can be found here: https://github.com/nate-double-u/technical-documentation-versioning.

Footnotes

  1. Batard, T. (2020, August 13). VMware-Tanzu/velero. GitHub. Retrieved January 19, 2021 from https://github.com/vmware-tanzu/velero/blob/ db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html ↩ ↩2

  2. Brubaker, N., Rosland, J., Thompson, C., Batard, T. (2020, September 16). VMware-Tanzu/velero. GitHub. Retrieved February 2, 2021 from https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml ↩

  3. Pursley, B., Horgan, C., Takahashi, S. (2020, July 21). Kubernetes/website. GitHub. Retrieved February 2, 2021 from https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html ↩

  4. Bannister, T. et al. (2020, December 23). Kubernetes/website. GitHub. Retrieved February 2, 2021 from https://github.com/kubernetes/website/blob/ 7462297ee388332a7b0d27625929fbf44d0c1ea9/config.toml ↩