Blog Archives

How to add a banner to website pages using Hugo

A while back, I needed to display a banner on every page of a documentation website. Furthermore, I wanted the banner to appear only under specific conditions. We use Hugo as the static site generator for the website. Here’s what I figured out, using Hugo templates.

I wanted to add a banner to the archived versions of the Kubeflow documentation, such as v0.7 and v0.6, letting readers know that they’re viewing an unmaintained version and pointing them to the latest docs.

Here’s an example of such a banner:

In Kubeflow’s case, the purpose of the banner is to catch people who enter the archived documentation from a web search and make sure they realise that a more up-to-date set of docs is available.

Summary: Adding a banner to a page with Hugo templating

In essence, you need to do the following:

  • Figure out which Hugo layout file is responsible for the base layout of your pages. In the case of the Kubeflow docs, the responsible layout file is at layouts/docs/baseof.html. You can see an example of the layout file in the Docsy theme: layouts/docs/baseof.html. (Kubeflow uses Docsy on top of Hugo.)
  • Add the code for your banner to the layout file. Or, even better, create a partial layout, often called just a partial. A partial is a snippet of code written in Hugo’s templating language. Put the code for your banner into the partial, then call the partial from the base layout. For the Kubeflow version banner, the code sits in a Hugo partial named version-banner.html.

There’s an explanation of the code later in this post.

Making the banner’s appearance conditional

In order to offer docs for multiple versions of Kubeflow, we have a number of websites, one for each major version of the product. The overall configuration of the websites for the different versions is the same. For example, we have the current Kubeflow documentation, and archived versions 0.7 and 0.6.

I wanted to make sure we had to do only minimal extra configuration to cause the banner to appear on the archived doc sets. I didn’t want to have to edit the layouts each time we create an archive. A good solution seemed to be a parameter that we can set in the site’s configuration file.

How it works – first the configuration settings

The parameter that controls the appearance/non-appearance of the banner is named archived_version. If the parameter is set to true, the banner appears on the website. The parameter value is false for the main doc site, When we create an archived version of the docs, we set the parameter to true.

The parameter is defined in the site configuration file, config.toml. The configuration file also contains a version number and the URL for the latest version of the docs. Both these fields are used in the banner text.

Here’s a snippet showing the relevant part of the configuration file:

# The major.minor version tag for the version of the docs represented in this
# branch of the repository. Used in the "version-banner" partial to display a
# version number for this doc set.
version = "v1.0"

# Flag used in the "version-banner" partial to decide whether to display a
# banner on every page indicating that this is an archived version of the docs.
archived_version = false

# A link to latest version of the docs. Used in the "version-banner" partial to
# point people to the main doc site.
url_latest_version = ""

How it works – the content and logic

For the Kubeflow website, a Hugo layout file is responsible for the base layout of the documentation pages:layouts/docs/baseof.html. You can see an example of the layout file in the Docsy theme: layouts/docs/baseof.html. (Kubeflow uses Docsy on top of Hugo.)

I inserted the following line into the base layout:

{{ partial "version-banner.html" . }}

The above line calls a Hugo partial named version-banner.html. The partial contains the banner content and logic. (I’ve contributed the logic for the version banner to Docsy, which is why the URL leads to the Docsy repository.)

Below is a screenshot of the content of the partial. Unfortunately I can’t paste the code, because WordPress strips out all HTML:

You can copy the code from the partial: version-banner.html.

The code does the following:

  • Check the value of the archived_version parameter. If true, continue to the next step.
  • Get the value of the url_latest_version parameter, for use in the banner content when giving readers a link to the latest version of the docs.
  • Get the value of the version parameter, for use in the banner content when showing readers the version of the website that they’re viewing.
  • Create an HTML div containing the styling and content for the banner.

Here’s the screenshot of the banner again, so that you can compare it to the HTML div:

Docs or it didn’t happen

I created a user guide for other people who want to use the banner logic on their sites using the Docsy theme: How to display a banner on archived doc sites.

I also updated the release procedures for the Kubeflow engineering/docs team, explaining that we must set the archived_version parameter to true when archiving a website version.

In closing

I hope this post is useful to you, if you find that you need to add a banner to a website using Hugo templating!

Countdown to the first Write the Docs Sydney meetup of 2020

A new year. A new decade. New friends and old. New skills. New ideas. It’s all happening in Sydney at the first 2020 meetup of Write the Docs Australia’s Sydney group. The date is nearly upon us!

The meetup is open to technical writers in all disciplines, and to engineers, editors, product managers, and others I’ve unwittingly left out. If you think technical documentation is a good thing, you’re in. If you think technical documentation is not a good thing, you’re in too. Just be prepared to explain your reasoning. 🙂

  • Date and time: Tuesday 25 February at 6pm to 7.30pm.
  • Location: Google, 48 Pirrama Road, Pyrmont. (Map.)
  • Registration: Sign up to the meetup and then click Attend, or email me. Details are on the Meetup page.

Pizza and conversation are a given. We also have two talented and interesting speakers lined up:

David Parker (Deaf Dave) will talk about Accessible Media for the Deaf and Hard of Hearing.

From David:

My short presentation will be about how accessible media is for the deaf and hard of hearing communities in Australia and worldwide. Digital examples will be given. I will talk about myself as a Deaf person and how I utilise technology to do my job effectively.

Giles Gaskell will talk about Using Antora to build public and internal docs sites.

From Giles:

At Squiz, we’ve built a powerful documentation system with Antora. This presentation provides an overview of how we’ve used Antora and other tools to produce both our public documentation site, and an internal site with additional docs for review and Squiz staff only.

I’m looking forward to this gathering of doc-aware people! I hope you can make it.

The second Kubeflow doc sprint is happening in February

The first Kubeflow doc sprint took place in July this year. It was so good that we’re going to do it again in February 2020!

This time round, our focus is on use cases. A few weeks ago I wrote about our doc analytics, and in particular how the “use cases” section had jumped into the top ten most viewed areas of the docs. When arriving at the use-case docs, though, people are disappointed in what they find. We need to improve that.

There’ll also be some juicy bugs to dig into. We’re preparing our list of docs to write/fix in the doc sprint Kanban board.

Event details

Dates: Monday, February 10, to Wednesday, February 12, 2020.
Location: Sunnyvale, CA, or remotely from anywhere in the world.

To find out more about the upcoming doc sprint, read the announcement on the Kubeflow blog.

Analytics strategies for evaluating and planning doc updates

Over the past few months, I’ve been delving into analytics and feedback on the doc site that I currently manage. I’m crafting strategies as I go, and creating reports for product stakeholders to get their input too. I hope some of the strategies described in this post may be useful or at least interesting to other people who’re looking into how to use analytics.

Note: Although I work at Google, this post does not constitute any recommendations on the use of any Google product. I’m a technical writer, and I’m using analytics and feedback in the same way other tech writers do, to gain insights into the doc set that I manage. I am by no means an expert on analytics.

Let’s get some technical details out of the way first. The doc site under discussion is, which hosts the documentation for an open source machine learning platform called Kubeflow. The documentation is also open source. The source for the docs lives on GitHub.

I’m using Google Analytics to see the doc usage stats. The Kubeflow doc site is fairly new. I enabled Google Analytics and the feedback widget on February 27, 2019, which means that the stats start from that date.

To gather user ratings on the doc pages, I’m using the feedback widget that’s available with the Docsy theme. The Kubeflow website uses Docsy and Hugo. If you’re interested in the details of the website tooling, take a look at the website README.

Goals for the analytics reports

The Kubeflow community and I are interested to see how people are using the docs. A high percentage of page views in a particular area can indicate a high level of interest in the related product features, or can point to an area of the product where people need more help than in other areas.

From a docs point of view, my goal is to identify the top priority docs for improvement, and to get some direction on the types of improvements we need to make. For example, if people are particularly interested in an area of the docs, and at the same time are not satisfied with the information they find there, then that area of the docs is high priority for improvement.

Overall site views

I started by looking at the number of website views from March (when Google Analytics became available on the site) to November (now). The number of views per month has more than doubled in that time, from 104,000+ to 220,000+. It’s good to know our reader base is increasing.

Total website views

Most-viewed pages

I looked at the pages with highest number of views across the site as a whole, and also within a few high-priority sections of the docs.

The period for these stats is two months, from September 1 – November 1. Our previous report was in July. I didn’t include August in the stats, because we did some information architecture refactoring in August. We moved many pages around. Moving pages affects the Google Analytics stats, which makes August a bad month to use for assessments in this case.

Most-viewed pages

The top entry, “/”, denotes the Kubeflow website home page: This page consistently receives the highest number of views.

As in previous reports, the second-most viewed page is the main Getting Started guide. It’s linked from the website home page. Other getting-started guides rank highly too.

Also as in previous reports, the third-most viewed page is About Kubeflow. It’s linked from the top-level menu bar with text “What is Kubeflow”.

In a change from previous reports, the Use Cases section has replaced components and notebooks in the list of 10 most-viewed sections. I should start paying attention to this section.

Other pages in the top 10 are the same as in previous reports: the docs index page and the pipelines section.

Strategies for most-viewed sections and pages

My overall strategy for the top-viewed pages is to spend time perfecting the user experience on those pages, addressing any issues, and making sure people find the information they need:

  • Improve the textual and visual content of the most-viewed pages. For example, we recently ran a doc sprint in which we spent considerable time restructuring and rewriting the website home page, which is the most highly viewed page in the doc set. Feedback on the new design and content is good.
  • Link from the most-viewed pages to content deeper in the site, to ensure people find all the information they need. For example, we recently rewrote the “About Kubeflow” page and added links down into relevant content on the site.
  • Examine the bounce rate and time on page, to see how people are using the page.
  • Examine feedback, to see whether people are finding the content useful.

Getting feedback from readers

Every page on the Kubeflow website has a feedback option. The option asks “Was this page helpful? Yes / No”.

  • About Kubeflow received the most feedback, and 24 of 28 responses (85.7%) were positive. That’s an improvement from the July analysis, which showed 70% positive.
  • Getting Started received the second-most feedback, and 11 of 15 responses (73%) were positive. That’s exactly the same as in July.

It’s worth noting that the number of feedback responses is very low in comparison with the number of page views. Also, people are more likely to respond with negative feedback than with positive. Even so, the feedback is useful, particularly when it’s strongly positive or negative, and if the ratios of positive to negative change after we’ve updated the content.

Deep dive into specific sections and pages

Based on the above statistics and feedback results, I examined some specific pages in greater detail.

The next screenshot shows the 10 most-viewed pages within the getting-started section. We reorganized this section significantly in August. It’s useful to see which getting-started experiences are the most often viewed, in the period since that significant refactoring.

The guide to deploying Kubeflow on an existing Kubernetes cluster (roughly equivalent to on-premises installation) has most views. The workstation installation guides come next, followed by deployment to a cloud.

The following stats are for the Getting Started page, which introduces the getting-started section:

Looking at the information for this getting-started overview page in detail:

  • The page has the second-highest number of page views in the entire doc set (the top-level page has highest).
  • Bounce rate* has continued dropping, from 56% in April to 44.15% in July, to 39.6 percent now. That’s a great improvement. Our goal was see it drop below 40% – goal achieved!
  • Time on page is 1 minute 7 seconds. That’s fine. There’s no need for people to spend longer on the page, because this is an overview page and the meaty content is in sub-pages.
  • The getting-started overview page has received the second-highest amount of feedback of all pages on the site , and 11 of 15 responses (73.3%) were positive. That’s exactly the same as in July.
  • Overall, the getting-started pages continue to receive low ratings.

* The bounce rate for a page is the percentage of user sessions that started and ended with that page. So, people entered the site on that page, and left without viewing any other pages. I’ve seen guidelines indicating that, as a general rule, we should avoid a bounce rate higher than 70%. If many people visit a page but leave immediately, this may indicate that the page isn’t giving them what they need, and so they leave the site. (It does depends on the type of page. The purpose of some pages is exactly to send people elsewhere.)

We need to improve the content of the getting-started section so that it better meets the readers’ expectations. One tactic I hope to follow, if I can get time from a UX research team, is to test the pages with some specific groups of users. In addition, I’ve already seen feedback from customer issues that people are looking for a single, recommended flow for getting started quickly. Currently the docs offer all the options, but don’t give much guidance on where to start.

Next up is the About Kubeflow page:

Looking at the About Kubeflow page in detail:

  • It’s the third-most highly viewed page on the website.
  • In previous reports, bounce rate came down from 63% in April to 60.4% in July. Bounce rate has now gone up again to 62%. We need to lower the bounce rate, as this page is a highly-viewed page and we want to draw people deeper into the site. I’m working on a new Kubeflow overview (pull request #1339). When that new page is available, I’ll link to it from the About Kubeflow page, and then re-assess the bounce rate.
  • Average time on page is two minutes. That’s good for an overview page. People are engaged in the content.
  • The page has received the most feedback of all pages on the site, and 24 of 28 responses (85.7%) were positive. That’s an improvement on July (70% positive).
    We refactored the page in June to provide more information and links. I hope to improve the positivity still further by linking to the new Kubeflow overview mentioned above.

What about the Use Cases section, which has recently made it into the top 10 most highly viewed sections?

  • It’s interesting to see a set of guides arrive in the top 10 most highly-viewed pages for the first time. This change potentially indicates that our audience is maturing and looking for more in-depth use-case focused docs. The product (Kubeflow) is relatively new, and is currently working towards a v1.0 launch in 2020. Up now, perhaps most people have been focused on getting the product up and running and trying the simple use cases provided in the getting-started section. Now maybe they need more in-depth use cases.
  • The feedback ratings on this section are low. We need to make sure people get what they’re looking for.
  • One action I’m considering is to adjust the information architecture to reflect what people are probably looking for. At least in the short term, I could rename the section, as it describes highly specific ways of using the product, rather than the more generic use case information that people may be looking for. Alternatively, I could move the content into another section, such as the “further setup and trouble shooting” section.
  • Then, when we have more bandwidth and have had time to do more research, we should flesh out the section with more use cases. We do already have some good examples and tutorials, which we can include in this section.

Open source contributors to the docs

Moving from Google Analytics to GitHub stats for the doc repository, it’s interesting to see the fluctuation in the number of contributors to the docs. It’s not just me writing the docs!

The following events influenced the contributor numbers:

  • We ran a community-wide Kubeflow doc sprint in July. Contributions increased significantly during that period, and stayed high for a while afterwards.
  • Contributions picked up towards the Kubeflow v0.7 release, which happened in early November.
  • In mid November, we ran a doc fixit for external tech writers at the Write the Docs conference in Australia. That fixit causes the large spike at the right-hand edge of the graph.

We need to run more doc sprints and fixits!

Traffic sources

A product stakeholder requested information about the sources of website traffic. I haven’t yet figured out any related strategies.

In the period August 1 – November 1, 2019, close to 60% of the website traffic came from organic search. Referrals accounted for 22%.

Traffic sources

I looked at the referrals, and found that the largest percentage (29%) of referrals come from GitHub. This is not surprising, given that the source code for the product is also on GitHub. The next-largest percentage is 8.5%, coming from a related doc site.

The top 10 search terms are primarily variations of the product name, “Kubeflow”, with one outlier: “minikf” at number 4. MiniKF is a deployment tool for Kubeflow.

Search terms

More analytics tips?

If you have any analytics tips or experiences to share, I’d love to hear them. Links are welcome!

From the Tech Writing 101 workshop at Write the Docs AU 2019

Sydney hosted the annual conference of Write the Docs Australia this week. As part of the conference, I ran a Tech Writing 101 workshop. It was a very rewarding experience. If you ever consider running a conference or workshop for a group of technical writers, do it! Tech writers are an engaged, humour-loving, smart group of people.

The workshop

The workshop teaches the principles and patterns of effective technical writing. Before the event, the participants do some pre-reading. Then, during the two-hour workshop, we do a series of exercises and discussions based on the principles in the pre-reading. This is a good way of cementing the patterns into your brain. The next time you write an overlong sentence, or use the passive voice, you’re likely to recognise the anti-pattern and do something to correct it.

We had around 45 participants at the workshop during the conference. Here’s a shot of the room during the workshop. At this stage, the participants had just finished one of the exercises and were discussing their solutions with their partners:

Three assistants helped with running the workshop. They walked around the room answering questions, assisting with logistics, and generally making sure everyone had a good experience. A big thank you to:

The Tech Writing 101 workshop was developed by tech writers at Google to train engineers and others in the principles of effective technical writing. Google is currently preparing a revised, improved set of pre-reading and presentation content, which will be available for tech writers all over the world who want to run the workshop. Stay tuned for news on this front.

What else happened at the conference?

Write the Docs Australia 2019 was jam-packed with talks, workshops, lightning talks, and unconferences. Take a look at the full program.

Here’s the Twitter hashtag: #wtdau2019.

Thanks so much to all the organisers and attendees. Write the Docs AU 2019 was awesome. See you at Write the Docs AU 2020!

%d bloggers like this: