Author Archives: Nicole Radziwill

“Documentation” is a Dirty Word

I just skimmed through another 20 page planning document, written in old-school “requirements specification”-ese with a hefty dose of ambiguity. You know, things like “the Project Manager shall…” and “the technical team will respond to bugs.”

There’s a lot of good content in there. It’s not easy to get at, though… for each page I want to understand, I can expect to spend between ten minutes and an hour deciphering what’s going on. (That’s half a week of work, and I have a lot of other work to do this week. Is it even worth it?)

Also, this document is boring… and there’s a lot of filler (like “package X is useful, flexible, and open source” – OK, that’s great, and factually correct, but not very informative).

The whole document could have been condensed into 4 or 5 slides of diagrams plus annotations. If that had happened, I’d be looking at a 10 to 30 minute commitment overall to get my brain into this particular company’s context… and then I’d be able to make some useful contributions. (As it stands, I’m weighing whether it’s worth my time to go spelunking in that 20-pager at all. Probably not.)


  • The bulk of technical documentation that I read is unintelligible or lacks sufficient meaning. I have three decades of exposure to this stuff, so if I can’t understand it, I feel super sorry for the early career people (who might think they can’t understand it because they don’t know enough).
  • Nearly all of the technical documents I see are uninteresting. And tech is interesting.

99 times out of 100, technical documentation is dull and dysfunctional. While it’s supposed to help people and teams establish a shared understanding of a system or a process or a concept, it just ends up looking really impressive and convincing you that the authors know a lot more about this than you do. It doesn’t help you much, if at all.

And as a CTO, CIO, or VP of Engineering, I don’t want to pay for crappy documentation. This particular document probably cost me between $32K-50K, and that’s just the tip of the iceberg… because it doesn’t account for the incremental costs of the people who will attempt to decipher it – which could be 10-100x more over the lifetime of that document. Although the person or team that wrote the 20-pager probably knows what’s going on (at least a little bit), the artifact itself is going to cost other people time and take them away from more value-adding tasks.

The sheer volume of information we’re required to wade through to gain understanding – without the assurance that it will lead us in the right direction, or even in any direction at all – is probably what’s led to the disease of devaluing documentation

A lot of managers think documentation isn’t value-adding, and shouldn’t be done, because… in most cases, people do it so badly that it wasn’t worth the investment in the first place.

Dear tech workers: can we fix this, please? I know it will take a whole generation to effect meaningful change, but… I’m ready to roll up my sleeves.

Scrum and the Illusion of Progress

Agile is everywhere. Sprints are everywhere. Freshly trained Scrum practitioners and established devotees in the guise of Scrum Masters beat the drum of backlog grooming sessions and planning poker and demos and retros. 

They are very busy, and provide the blissful illusion of progress.

(Full disclosure: I am a Sprint Grinch, and my heart will not grow three sizes, or even one… on any day.)

Despite the mirage of progress, the people on the front lines doing the engineering work feel little relief from the ill logic and misplaced pressure of the pointy haired bosses. The managers aren’t getting the deliverables faster (like they convinced themselves they would). There are tons of charts and graphs that tell us how we’re doing (like burndowns) but now the CFO is using them to whip our horses just a little bit harder, trying to get them to go faster. They’re not going fast enough. (Spoiler: They will never go fast enough.)

And isn’t that what Agile is supposed to do… speed things up? NO!

Once upon a time, we used to build software like we built skyscrapers: plan every single task, put in on a Gantt chart, and make sure there are approval gates between every phase of work: elicit requirements, design the systems, write code, test it, deploy it, maintain it.

But a couple of big, bad things tended to happen over and over: 

  • By the time we got to “test and deploy” we’d discover that the thing we built was not what the users and stakeholders actually needed. (“But it’s exactly what you asked for in the requirements,” we’d say, “and you approved it at multiple decision points.” “Sure,” they would say, “but we learned a lot in the meantime, and things are different now. You just built us what we thought we needed six months ago.”)
  • The software developers would build something that the operations team, responsible for standing it up and maintaining it, wouldn’t be able to support at the intended service levels. (“You can’t expect us to maintain this,” they’d say. “It’s fragile.”)

Agile practices emerged more than two decades ago when engineers said… hold it, there’s got to be a better way. If we work collaboratively with our users and stakeholders, learning together, figuring out how to realize value together… then we’ll produce something that real people are able to get value from much faster. We need control over our process, and we need you to be actively engaged, business people. We can eliminate all these handoffs, and replace them with shared accountability.

The two solutions were: 

  • Agile: We said “let’s take a more collaborative approach to development, and get the users and stakeholders together with the engineers, so they can all learn and co-create together until they’ve produced the next nugget of value.” 
  • DevOps: Instead of two groups siloed from each other, let’s automate the handoff and make it seamless, and give the developers tools that will alert them when they’ve got to fix more stuff. If tests automatically run before the code is merged into production, we’ll always know that we’re deploying stuff that runs. (I’m pretty sure everyone agreed this was a good idea.)

Agile is a great aspiration. But how often have you ever seen the users and stakeholders sharing space, sharing accountability, sharing the process of creating value? Not often. They still coordinate through user stories, and tickets, and handoffs, and PRs. 

Agile speeds up value delivery, but not necessarily software delivery. Having daily stand-ups and burndown charts and JIRA tickets won’t make people code faster. But it will make managers think they should be coding faster, and that’s where the poison will settle in and grow.

Bottom line, my position statement is:

  1. Any (minimalist) process is better than no process.
  2. Agility is an essential goal, but Scrum and certified Agile practitioners are less likely to get you there.
  3. Go back to first principles: plan an iteration, co-create value, see where it got you and reassess your ability to reach your goal, then adjust. Keep experimenting.

Would I ever use Scrum? Sure, under specific conditions:

  • There’s something we have to build, and we’ve never built it before.
  • The road ahead is unknown.
  • We have access to collaborators who can help us see what’s needed.
  • We agree to intentional checkpoints where we can see how far we got, and whether we can still get to the place we’d originally intended.
  • We iterate, and iterate, until we agree we’ve incrementally added enough total value nuggets to move to the next project.
  • There are no well-meaning-but-not-helpful engineering managers or business managers hovering over the development team with bated breath, waiting to beat us with burndowns. The dev team can manage itself.

Agility is a laudable – and essential – goal. But only in rare cases do I believe Agile and Scrum will get you there.

Why Software Estimation is (Often) Useless

For 12 years, I blogged and wrote a whole bunch. For the past year and a half, I’ve let myself be pulled away from so many of the things that make me me… including writing. Today I heard one of the best anecdotes ever, and it’s the spark that will be pulling me back in. (Thanks, John.)

So here it is! It has to do with software estimation. Not only is it difficult to accurately estimate how long it’s going to take someone to do a programming (or similarly technical) task, the act of estimating often does not add any value at all. Estimation is a bad thing, especially if you’re trying to be Agile.

(And if you’re in a client/contractor relationship, you’ll have discovered that estimates are the lifeblood of the relationship, even as they drain all the life and all the blood out of the relationship, slowly and deliberately.)

Sometimes I get caught asking engineers for estimates even when the task we’re embarking on is new, unknown, uncertain, and requiring lots of learning and exploration and discovery. I should know better. But I cave, because the concept of the software estimate is so enticing: with a good estimate, I’ll know exactly how much time someone will need to spend working on a task that’s still kind of nebulous and mostly unknown. (That was a joke.)

My friend John shared the best anecdote ever today about why software estimation is so frustrating (liberally embellished):

Imagine that you’re standing on a hill looking down at a labyrinth, or a corn maze. It’s reasonably small… you can see that the corn maze is definitely doable, you can see a couple paths in and out, and the entire maze is a similar size to other mazes you’ve successfully found your way out of. So you’re pretty sure once you get to the entrance, you’ll find your way out.

But there’s no way you can say exactly how long it will take you to escape. Maybe you’ll run right through from start to finish, and it will be smooth. Maybe you’ll get stuck in the beginning, and spend a long time before winding your way out. Maybe you’ll run right close to the end, but have no idea you’re a few feet away from the exit, and you’ll get stuck there for a while.

And maybe you’ll make it halfway through, get lost, go in circles, and eventually just die in the maze.

Problem is, I can tell you how long it’s taken me to get across comparable mazes, but I have no way of knowing how long it will take me to escape from this maze, and just having another engineer in the maze to pair with me and see things I’m maybe not seeing is no guarantee at all that either of us will get us. Statistically, we’ll probably make it out, but the estimate I give you is just a guess.

Unfortunately, it’s a guess that’s going to make a lot of people unhappy, no matter what. Because even if I make it out of the maze fast this time, then they’ll expect that I’ll zoom through the next maze.

– John

Turn on your Domain Name for a Hugo Site on Google Cloud (PART 4)

You’ve got your Hugo site built, and in a public GCS bucket, and you can see it by going to the URL at — now how can you make http://yourdomainname.yourtld work directly? This post assumes that you’ve already purchased a domain from and you have a Hugo site (or any other web site) set up in a GCS bucket.

Step 1 – Get into the domain administrator panel. Go to and click “My Domains” in the top right of the window.

Step 2 – Find the domain that you want to map to this bucket and click “Manage” on the rightmost side of that line.

Step 3 – Click “Edit DNS Settings” OR “Use custom name servers for your domain” – they both go to the same page.

Step 4 – Scroll down to “Custom Resource Records”:

  • In the textbox that says @, type www
  • In the dropdown, select CNAME
  • Keep 1H in the next textbox
  • In the last textbox, type (that last dot is important, too)
  • Click Add

Step 5 – Add a Synthetic Record so your “naked domain” (no www) will work. In the “Synthetic Records” section, put an @ in the first box, put http://www.yourdomainname.yourtld in the rightmost box, and click “Forward Path” in the middle group of radio buttons. Click Add and this should make the magic happen.

Step 6 – Wait. They’ll say it takes up to 48 hours for DNS to propagate… it usually takes a lot less. Even though you set up the CNAME to trigger from www, Google Domains automatically catches www and no subdomain, so you should be able to go to http://yourdomainname.yourtld. Check your custom URL after an hour or two! If the site isn’t available by the next day, though, there may be a problem in your GCS bucket or your setup.

Good luck! And remember to check out the “I want to get off Squarespace” project that motivated these posts…

Pushing Your Hugo Site to a GCS Bucket (PART 3)

By now, you’ve build a gorgeous Hugo site that you admire at http://localhost:1313 that no one but you can see. This post aims to help you fix that, by taking the first deployment step: putting your Hugo site into a GCS bucket. This assumes that you also have git bash installed with the Google Cloud SDK (gsutil), and that you’re familiar enough with that you can log in and double check your settings. This also assumes that you’ve purchased a domain name that you administer through Now! to begin.

Step 1 – Build your Hugo site. Even though you can view it on localhost, the static site hasn’t been built yet.

cd /d/Hugo/myrealsite

That’s it! The GO engine behind Hugo just created a ton of static web pages on your behalf, and popped them into the /public directory. Go into that directory and ls -spla just to make sure stuff is there.

Step 2 – Use gsutil to set up your new bucket and tell Google Cloud that it will be a web site. You should still be sitting in /d/Hugo/myrealsite. Note: The domain name MUST have www in the beginning, even if you want to direct people to yourdomainname.yourtld.

gsutil mb gs://www.yourdomainname.yourtld
gsutil web set -m index.html -e 404.html gs://www.yourdomainname.yourtld

Step 3 – Make everything in that bucket public so people on the internet have the permissions to get to your page. This part was a little tricky for me, because I’m not sure exactly which command made it work, but I can tell you how to double check. Start by doing one (or both) of these:

gsutil defacl ch -u allUsers:R gs://www.yourdomainname.yourtld
gsutil iam ch allUsers:objectViewer gs://www.yourdomainname.yourtld

When you go into, head to Storage -> Browser. Find the line item that has your http://www.yourdomainname.yourtld name that you just created. In the “Public Access” column, there should be a little orange warning icon and the words “Public to Internet”. If you don’t see that, then Google around for more advice on “how to make the contents of your GCS bucket public to the internet”.

While you’re in there, check to make sure the bucket is set up to serve a web page. On the far far right side of that same line, you’ll see three vertical dots. Click on them, and go into “Edit Website Configuration”. The top textbox should say index.html and the bottom should say 404.html. If they don’t, make them say that, and then click Save.

Step 4 – Populate your GCS bucket with your built Hugo site in /public (not the raw files you edited). Make sure you’re still sitting in /d/Hugo/myrealsite and then do this:

gsutil rsync -R public gs://www.yourdomainname.yourtld

Step 5 – You now have a Hugo web site on Google Cloud! Test it out by pointing a browser to (being sure to put your actual domain name in there) — if you get a permission error or an XML dump, go back to Step 3 because something went wrong there.

Now it’s time to link your bought domain name with your publicly visible Hugo web site!

Building Your Hugo Site Locally (PART 2)

…continued from which is part of the series summarized at

Now that you have Hugo set up on your machine, it’s in the Windows PATH, and you’ve verified it by checking hugo version, it’s time to build your first web site on localhost (your own machine).

Step 1 – Open git bash and go to your Hugo directory (for me, cd /d/Hugo).

Step 2 – Let’s pull down a theme from and look at its exampleSite it provides. The theme we will work with is Vanilla Bootstrap, because this is the one that datalorax initially inspired me with. Go to that URL, and the next few steps will (sort of) mirror steps you see there.

Step 3 – Create a new space for a hugo site. We will call it mytestsite:

hugo new site mytestsite

Step 4 – That creates a new directory under your Hugo directory called mytestsite. Switch into it, do a git init, and then pull the theme into your new hugo site directory like this:

cd mytestsite
git init
git submodule add themes/vanilla-bootstrap-hugo-theme

This is going to create a whole new subdirectory structure. For me it looks like this: /d/Hugo/mytestsite/themes/vanilla-bootstrap-hugo-theme/

Step 5 – Switch into the home directory of the exampleSite and edit config.yaml with your favorite text editor. I use nano. You want to change the baseURL to say http://localhost:1313. Save config.yaml when you’re done.

cd /d/Hugo/mytestsite/themes/vanilla-bootstrap-hugo-theme/exampleSite

$ cat config.yaml
languageCode: en-us
title: Vanilla
theme: vanilla-bootstrap-hugo-theme
googleAnalytics: UA-123456789-1
...more stuff...

Step 6 – Now go into the theme itself and add draft: false to tell it that none of the pages should be thought of as a “draft” – and thus be invisible when you build your first site. If you forget this step, building the Hugo site will produce a lovely single HTML page with only opening and closing PRE tags.

cd /d/Hugo/mytestsite/themes/vanilla-bootstrap-hugo-theme/archetypes
$ cat /d/Hugo/mytestsite/themes/vanilla-bootstrap-hugo-theme/archetypes/
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: false

Step 7 – Now it’s time to go back to the exampleSite directory, make one tiny more change to a file! and build your exampleSite. The change to make is to edit so that you see draft: false for the same reason as in Step 6:

cd ../exampleSite
$ cat
title: Home
draft: true
     # CHANGE THIS TO FALSE!! then re-save the file

Homepage content goes here.

Now you’re ready to build:

$ hugo server --themesDir ../..
Start building sites …

                   | EN
  Pages            | 57
  Paginator pages  |  0
  Non-page files   |  3
  Static files     |  5
  Processed images |  3
  Aliases          |  0
  Sitemaps         |  1
  Cleaned          |  0

Built in 43 ms
Watching for changes in D:\Hugo\mytestsite\themes\vanilla-bootstrap-hugo-theme\{archetypes,exampleSite,layouts,static}
Watching for config changes in D:\Hugo\mytestsite\themes\vanilla-bootstrap-hugo-theme\exampleSite\config.yaml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address
Press Ctrl+C to stop

Step 8 – Now, pull up a browser and point it to http://localhost:1313 and you’ll see what you just created!

Step 8 – Now it’s time to build your OWN site. (You can see at this point why I was dismayed… there is not enough instant gratification in setting up the exampleSite. Also, because of documentation issues, it took about a day to get it to work.) It’s your turn to have an easier time than I did. Let’s use the Set up your own new web site using the Showcase theme (which I selected because it looked simple and… what could possibly go wrong with that one? hahaha). First we need to launch their exampleSite, just like for the other theme:

cd /d/Hugo
hugo new site myrealsite
cd myrealsite
git init
git submodule add themes/showcase

This will create a complete directory structure for you:

$ ls -sapl
total 14
4 drwxr-xr-x 1 User 197121   0 Dec 23 08:04 ./
4 drwxr-xr-x 1 User 197121   0 Dec 23 08:04 ../
4 drwxr-xr-x 1 User 197121   0 Dec 23 08:04 .git/
1 -rw-r--r-- 1 User 197121 112 Dec 23 08:04 .gitmodules
0 drwxr-xr-x 1 User 197121   0 Dec 23 08:04 archetypes/
1 -rw-r--r-- 1 User 197121  82 Dec 23 08:04 config.toml
0 drwxr-xr-x 1 User 197121   0 Dec 23 08:04 content/
0 drwxr-xr-x 1 User 197121   0 Dec 23 08:04 data/
0 drwxr-xr-x 1 User 197121   0 Dec 23 08:04 layouts/
0 drwxr-xr-x 1 User 197121   0 Dec 23 08:04 static/
0 drwxr-xr-x 1 User 197121   0 Dec 23 08:04 themes/

Here’s where many of the docs say “just hugo server -D and then see your site in the browser and localhost!!” and it is a lie. This lie is probably due to a new Hugo learner reading the docs incorrectly, but the experts are not aware that we will naturally do that because we don’t have the directory and file structure memorized yet. All you can see right now is the theme designer’s exampleSite, and only if you do exactly the following while you are sitting in /d/Hugo/myrealsite:

cd themes/showcase/exampleSite/
hugo server --themesDir ../..

Now open a browser and point it to http://localhost:1313 for some (almost) instant gratification.

Step 9 – Now let’s edit your site… cd /d/Hugo/myrealsite again. It’s time to make that showcase theme your own! (Don’t try to just hugo server when you’re sitting in /d/Hugo/myrealsite… it won’t work. You’ll get the blank page with PRE tags.) Let’s make some changes, too, for educational reasons: 1) Instead of 4 blocks on the main screen, let’s do 6… 2) let’s put in your own images and words over the images, then 3) let’s either add a custom message or remove useless whitespace, and 4) let’s make the social media icons in the bottom right bigger, so old people like me can see them.

It’s time to switch the baseURL on config.toml – but what they don’t tell you is that THIS IS THE WRONG config.toml. (They say “copy the file to your root directory” – what file? What’s my root? You get the picture.) You have to go retrieve the one in exampleSite and edit THAT one if you want ANY OBJECT AT ALL to show on your web page. (Again, this makes sense after you’ve been immersed in Hugo for a while, but did not make sense at first.) Do this:

rm config.toml
cp themes/showcase/exampleSite/config.toml ./

Step 10 – Now edit the real config.toml file with your favorite text editor. I use nano. You want to change the baseURL to say http://localhost:1313. Save config.toml when you’re done. (Some themes have toml files, and some have yaml files. Both provide site configuration. The choice of which one seems to be up to the theme designer.)

baseURL = ""
   # Make this http://localhost:1313 for now
languageCode = "en-us"
title = "Showcase Theme"
Paginate = 1000
googleAnalytics = ""
theme = "showcase"
disableKinds = ["taxonomy", "taxonomyTerm", "RSS"]

  author = "showcase"
  # This becomes the text in UPPER & LOWER LEFT of web page
  description = "Minimal, one page, theme for showcasing your work"
  message = ""
         # This will be printed right above your six image blocks
  hideAutoMenu = false
 # Don't change this or your entire menu in upper right will vanish

  name = "External"
    # This becomes the MENU OPTION at the FARTHEST top right of page 
  url = ""
  # This is the URL that the menu option above will link to

  facebook = ""
      # Change these URLs to your personal social pages
  twitter = ""
        # You can delete, but not add...
  instagram = ""
    # I tried adding "github" but then found out later
  linkedin = ""
      # only these 4 options are hardcoded into the theme :(

The only changes I’ll make are baseURL to localhost, author to my blog’s name, and message to a secret message you’ll see later.

Step 11cd into /d/Hugo/myrealsite/archetypes and edit exactly like you did in Step 7 above. That way, it won’t automatically think every new page you create is supposed to be hidden.

Step 12 – Now you should be able to see your (very minimalist) site. Get back into the root directory with cd /d/Hugo/myrealsite and type hugo server, then pop open a browser and go to http://localhost:1313. Voila! Sort of!

Step 13 – If you want to put blocks of images on the page (but of course!), you’ll need to copy over some more files from inside the themes directory that are not attached to exampleSite:

rm -rf layouts
cp -r themes/showcase/layouts/ layouts

Now you’ve got the skeleton for a web site in your /d/Hugo/myrealsite. Here’s where you need to know what all the pieces in /layouts mean:

$ ls -sapl
total 12
0 drwxr-xr-x 1 User 197121    0 Dec 23 08:52 ./
4 drwxr-xr-x 1 User 197121    0 Dec 23 08:52 ../
           # "template file which matches Hugo
0 drwxr-xr-x 1 User 197121    0 Dec 23 08:52 _default/
     # <-- Layouts Lookup Rules" go here
4 -rw-r--r-- 1 User 197121 1140 Dec 23 08:52 404.html
      # You need this to deploy to GCS
4 -rw-r--r-- 1 User 197121 1673 Dec 23 08:52 index.html
    # The actual HTML for your main page
0 drwxr-xr-x 1 User 197121    0 Dec 23 08:52 partials/
     # header, footer, logo, custom message

You realize that all these files are important when you try to build a site using hugo server without them. You get messages like:

Start building sites …
WARN 2020/12/23 08:59:25 found no layout file for "HTML" for kind "section": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN 2020/12/23 08:59:25 found no layout file for "HTML" for kind "section": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN 2020/12/23 08:59:25 found no layout file for "HTML" for kind "section": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

If you see ANY of these errors, they are telling you to go find new files and put them into /layouts/_default — but you won’t find those magical files in the theme anywhere. Here are the links to example files from – you can go there to click through directly. It’s about halfway down the page:

Step 14 – Now that you have the skeleton, it’s time to start adding content! (If you hugo server now, you’ll get a mostly blank page just like last time, because it’s looking for directories and files in /content and you don’t have them yet. We will fix that.) I’m going to choose three very specific directory names to illustrate Quirk #1. We’re also going to pull in totally random images that you have on your machine now that you’ve installed two themes: vanilla bootstrap and showcase. We put them in /static (the place where static files like css usually go) not because it’s a best practice, but because it’s the only practice I know (so far) that works. We change the name on the second file so it doesn’t overwrite.

cd /d/Hugo/myrealsite/content
mkdir books
mkdir code
mkdir services
cp /d/Hugo/themes/showcase/images/screenshot.png /d/Hugo/myrealsite/static
cp /d/Hugo/themes/vanilla-bootstrap-hugo-theme/images/screenshot.png /d/Hugo/myrealsite/static/screenshot2.png

Step 15 – Now we need to put markup files in those directories too, so the web site has something to display. We want to create one markdown page per card we want to see on the front page: so, two will go in each directory:

cd /d/Hugo/myrealsite/content

cp /d/Hugo/myrealsite/themes/showcase/exampleSite/content/projects/ books/
cp /d/Hugo/myrealsite/themes/showcase/exampleSite/content/projects/ books/
cp /d/Hugo/myrealsite/themes/showcase/exampleSite/content/projects/ code/
cp /d/Hugo/myrealsite/themes/showcase/exampleSite/content/projects/ code/
cp /d/Hugo/myrealsite/themes/showcase/exampleSite/content/projects/ services/
cp /d/Hugo/myrealsite/themes/showcase/exampleSite/content/projects/ services/

Step 16 – Go into EACH one of those files and customize it. DO NOT make the date in the future, or the file will not render on your web site. Here’s what the changes correspond to on the page:

 Big Words Over Image
date: 2020-06-15
subtitle: Small Words Under Image
image: ./filename-of-image-in-your-static-directory.jpg  # png will also work

Go ahead and edit all six markdown files if you want, but if you are getting tired (right?) you’ll be able to see enough of what you need if you just edit two of them. I made the two files in /books look like this:

$ cat
title: Book 1
date: 2020-06-01
subtitle: The first book
image: ./screenshot.png

$ cat
title: Book 2
date: 2020-06-01
subtitle: The second book
image: ./screenshot2.png

Step 17 – Because our images are mostly white, we’ll also have to edit /d/Hugo/myrealsite/layouts/index.html to force the words that are superimposed over the images to be black, otherwise they will not appear against the light image:

            class="text-black px-2 py-1 tracking-widest text-2xl leading-tight
font-extrabold font-bree text-center w-full h-full flex justify-center items-center absolute t$
            {{ .Title }}
            class="text-black px-2 py-1 tracking-widest text-md leading-tight
font-light w-full text-center absolute bottom-0 left-0"
            {{ .Params.Subtitle }}

Step 18 – I also promised that I’d show you how to make the twitterbird (and other social logos at the far bottom right) bigger. Do this for EACH social logo you want to embiggen:

cd /d/Hugo/myrealsite/layouts/partials
nano footer.html

# then when you're in there... see those 5's? make them 10's:

      {{ end }} {{ if .Site.Social.twitter }}
      <a class="ml-3 text-gray-500" href="{{ .Site.Social.twitter }}">
          class="w-5 h-5"

          viewBox="0 0 24 24"
            d="M23 3a10.9 10.9 0 01-3.14 1.53 4.48 4.48 0 00-7.86 3v1A10.66 10.66 0 013 4s-4 9$
      {{ end }} {{ if .Site.Social.instagram }}

Step 19 – It’s finally time to build your own first Hugo site:

cd /d/Hugo/myrealsite
hugo server

Now head back to http://localhost:1313 — and by now, you should have enough background to fix those broken images and other error messages that you see. I’ll leave those as an exercise for the reader.

Step 20 – Now it’s time to push your site to a GCS bucket on Google Cloud. I know you’re exhausted, but this part will be relatively easy compared to what you just slogged through. In the meantime, check out the quirks I found in this theme as you celebrate your first victory.

  • Quirk #1: The subdirectories under /content turn into groups on your home page, each of which gets a menu option in the upper right corner. If the directory name you chose does not end in an S, the theme will automatically pluralize the word on the menu. For example, if you wanted a subdirectory called /code to create blocks on your home page, the little blue box in the upper right corner will say “Code” while the menu option says “Codes”. This is why on you see a menu item Repos that links to my blog and a github repo. I know a blog is not actually a repo, but technically it’s a repository of posts, so I used that technicality to rationalize my design choice instead of hunting for where this very much unmagical pluralization happens.
  • Quirk #2: I was not able to add more than one menu option in [[menu.main]] – even following documentation from many sources. I feel like there may be some quirk or hardcoding in this theme that limits you to one extra menu item beyond the list of subdirectories in /content, which automatically get posted to the menu.
  • Quirk #3: If you specify message="" in the config.toml and are disappointed that it leaves a huge padding of whitespace on your web page, you can take it out! I’ll spare you the agony of trying to figure out where. Go to /d/Hugo/layouts/, edit index.html, and remove line 5 that says {{- partial "custom-message.html" . -}} — this is Hugo’s very nice templating language, and if you stick with Hugo, you’ll learn how to build web pages that contain standard objects and special variables that describe the site, which is how you end up with a scalable, maintainable site. It is nice, it just takes a lot of elbow grease to be able to experience the nice.

Getting Started with Hugo (PART 1)

Hugo is a static web site generator. What that means is: it provides you with lots of templates, variables that you may want to see reappear throughout your site (and when changed once, update everywhere – like author name), and an engine that turns those templates into a lightning fast web site. That way, you can focus on the content rather than the presentation.

With Hugo, you will definitely be focusing on both though. But there’s a payoff: your website will be gorgeous, and even other people will notice (pretty much immediately) that it’s blazing fast. These steps assume that you have git bash installed, and that you’re working on Windows 10.

Step 1 – Open git bash and create a directory for all your Hugo adventures. Mine is on my D drive, but yours might be on C:

mkdir /d/Hugo

Step 2Download the Hugo executable to your machine, and put it in that directory you just created. Then, unzip all the contents into that same directory.

Step 3 – Add your new Hugo directory to the Windows PATH. Type env in the search bar at the bottom left of your screen and hit enter. On the window that pops up, click the Environment Variables button. In the bottom window, find the row that starts with Path and click it. Next, click Edit, then New. At the bottom of the list, add D:\Hugo (but put the directory YOU created on your machine! And be very careful about the direction of the slash).

Step 4 – Open git bash and type hugo version, then hit Enter. If you see a message like this one, Hugo is ready to go!

User@DESKTOP-4H0EUDG MINGW64 /d/Hugo (master)
$ hugo version
Hugo Static Site Generator v0.79.1-EDB9248D windows/amd64 BuildDate: 2020-12-19T15:44:19Z

…to be continued in next post

« Older Entries Recent Entries »