Planet Open Help

The life and work of the open help community
Join our planet

September 21, 2017

Anne Gentle Anne Gentle

Author of Conversation and Community: the Social Web for Documentation. I’m a writing fiend, technical geek, community doc nut, + Content Stacker for OpenStack.

Podcast interview talking about docs as code with Ellis Pratt of Cherryleaf

I had a great talk with Ellis Pratt of Cherryleaf Technical Writing consulting last week. Here are the show notes, full of links to all the topics we covered.

Podcasts are great fun to listen to and participate in, if a bit nerve-wracking to think on your feet and make sure you answer questions succinctly without too much meandering. I think it’s difficult to determine the depth to go into for docs-as-code techniques. I can go down a deep rabbit hole while explaining webhooks, continuous integration, and bash scripts, not to mention static site generators based in either Python or Ruby. Whew! Great chat, well worth the listen. Would love to hear your thoughts.

Wow, and the last time we spoke on a podcast was in 2009 after Conversation and Community: The Social Web for Documentation was released! Thanks Ellis for another engaging chat.

by annegentle on September 21, 2017 02:30 AM

August 01, 2017

Lana Brindley Lana Brindley

Writes too much, reads too much, talks too much, thinks too much, drinks too much. Generally superlative.

OMG my ACL! Two weeks post-op update

Well, here we are, two weeks out from surgery! There’s a lot to go through here, so I’ve broken it up a bit.

Day of surgery

The day went pretty smoothly, I had a quick coffee before 7am, and was fasting from then on. I headed over to the hospital at 10 and checked myself in. First thing was to change into a gorgeous hospital gown, with a compression stocking on my good leg, and delightful paper knickers and booties. You’ll forgive me for failing to instagram this, I hope!

From there, I had a consultation with a nurse to do my paperwork to check me in, the anaesthetist came to run me through what was going to happen, and the drugs I would have to take home with me, and I also had a quick chat to the pharmacist to go through the medication I was on already and whether or not I needed to change anything (I didn’t, so that was easy).

After all that, they laid me down in pre-op, the anaesthetist gave me the first injection, which made my head swim but I was still with it (although feeling pretty happy), they wheeled me into the operating theatre, and that was about the last thing I remember.

In recovery, there was a nurse waiting for me as I came around. I recall trying to work out if my leg hurt but couldn’t actually figure it out (drugs are great, aren’t they?). I was shivering uncontrollably, despite warm blankets, and very thirsty, though. The nurse gave me some water, and at some point I got moved to my room, where I fell back to sleep. It was about 7pm when I came around properly and could have something like a conversation (well, it seemed like a conversation from my perspective. Could have been meaningless gibberish and the nurses were too polite to mention it, though). At that point, I was conscious of my leg feeling uncomfortable, but it wasn’t really painful. I was given dinner which I didn’t really eat, and taught how to use the pain button.

I basically just dozed in short periods from there right through until morning, with interruptions due to nurses checking my blood pressure or giving me tablets, trying to find a more comfortable position, and one terribly exciting trip to the toilet which involved far too many people and an awful lot of equipment. My knee had a huge bandage around it, and my leg was encased in a splint. They did put an ice machine on my knee at one point but I couldn’t feel any cold through the bandages so they took it away. The most comfortable position was on my back with the head of the bed raised (really, it was the only position, I wasn’t very mobile at all).

Day after surgery

In the morning, rattling from all the pills I’d taken, I lolled in bed and read a book while a parade of people came past to see me. The physio gave me stretches to do in bed (quad activation, and ankle pumps for the calf muscle), then came back with crutches and we had a little lesson on partial weight bearing crutching, including stairs. The surgeon came to see me and told me he’d done not one but two meniscus repairs (lucky me!) and that everything went well and I was to come see him in two weeks to get the bandages off, the pharmacist came to talk me through my drugs, and then the nurses took my IV out (goodbye pain button!), bustled me off for a shower and to get dressed, and not long after lunch discharged me into the care of my Mum. I was going home!

Mum brought my car around to the front entrance, while an orderly took me out in a wheelchair (via the chemist to pick up my showbag). We put the front seat of my car all the way back, and I was able to sit down on the seat, swing my good leg in first, then use my hands to swing my injured leg in. At this point, I had zero ability to carry the weight of my lower leg in my knee, so using my hands to move my leg was essential.

Now, I know you all want to know what was in my showbag!

  • Palexia (Tapentadol): This one knocked me out something fierce. As soon as it was in my bloodstream, I was completely unable to stay awake. I took this one at night for a couple of days, which helped me to get some sleep in the first few days home.
  • Endone (Oxycodin): This one was actually a little scary for me. I took it once without the Palexia and found that I was lying in bed completely unable to move, but not asleep, and not without pain. I didn’t take it again after that.
  • Clexane: An anti-coagulant. This was an injection I had to take once a day for ten days to prevent blood clots. I got special instruction from the nurse on how to do it, and it wasn’t too difficult, except for the fact that after you’ve removed the needle it was sore for a couple of minutes and it was really hard not to rub the site. It also left pretty horrific bruises, but on the upside: no clot!
  • Paracetamol Osteo: My new favourite drug. It’s just like regular Panadol, but has a higher level of paracetamol (so no more than two every six hours!). The benefit of this over ordinary Panadol, aside from having more paracetamol, is that it has the regular stuff on the inside, with a coating of rapid acting, so it works fast, and keeps working. It helps to smooth out the up-and-down effect of regular paracematol. The extra added bonus is you can buy it over the counter at the chemist, and it’s super cheap.
  • Anti-nausea drugs, which I didn’t take because I didn’t have any nausea
  • Anti-constipation drugs: I took a Macrogol powder once a day, along with some Benefiber once a day (I had been taking Benefiber for the couple of days prior to the surgery as well, just to try and keep everything in good working order), but didn’t take the tablets in the end.

At home

Once I got home, my Mum put me to bed, brought me food occasionally, and otherwise left me alone to nap in front of the telly for about 48 hours. I watched the clock pretty carefully to make sure I was taking all my drugs at the right time, I got up to go the toilet (very gingerly) when I needed to, and otherwise tried not to worry about things. I kept my legs out in front of me in bed, propped my back and shoulders up on all the pillows to keep as comfy as possible, and tried not to move around too much. I found that I needed to keep the bottom corner of the doona flipped back off my foot, as it put pressure on my knee, and I didn’t really bother elevating it as it was mostly just uncomfortable to do so. I didn’t feel like eating much of anything at all, and I really didn’t want anything with a lot of carbs or spice (which is completely unlike me). I ate mostly salad, with a little grilled chicken, and drank lots and lots of water for those first few days.

The first week

Overall, the first few days were pretty miserable, but once the pain dropped and I could get rid of the heavier duty painkillers and move around a little more, things became much easier. I was down to Panadol only by Day 3 (although I was always very ready for my next dose as soon as six hours was up). Mum went home on Day 5, and by then I could get up out of bed and sit on the couch or a chair with my lower leg propped up on a beanbag and some pillows for at least short periods of time.

The second week

It was around the beginning of the second week that I started getting excruciating pain in my calf muscle. I spent most of the day (and night!) just pumping my foot up and down trying to relieve the cramping. Around Day 8 I made it a mission to make sure I was getting out of bed and moving around at least a little bit every hour, which helped during the day, but at night the cramps were keeping me awake. Pacing up and down your bedroom floor on crutches at 2am is not fun. On the upside, I wasn’t noticing any pain in my knee any more. I briefly wondered if it was a blood clot, but when I opened up my splint to massage the knots out of my calf, I noticed a small grey bruise (unlike the yellow bruises which had coloured my shin since the operation) right above the most painful part of my calf muscle, it was also not swollen or hot. I started to suspect the splint was to blame, and not a clot.

I drove for the first time on Day 9 (yay for hurting my left leg, living in Australia, and driving an auto!). I can go very short distances (less than 10-15 minutes before my knee starts getting sore) and I need to make sure I can open my door all the way so that I can get in and out (so no close parking!), but it’s enough to be able to drive down to the shops and get milk, or drop my daughter off, or go to doctor/physio appointments.

I saw my surgeon on Day 10 (and not a day too soon!), who agreed that the splint was probably causing the calf pain, but sent me for an ultrasound anyway just to be sure. He also removed my dressing to expose my gruesome wounds (which I have also failed to photograph. You’re welcome), put me into a compression stocking for swelling, and sent me off to get a new ROM brace.

The ultrasound confirmed no clot (yay!) and the new brace immediately helped relieve the pain. The splint had a foam strip that runs down the back of the leg, and the calf pain was occurring at the precise end of that strip. I gave it to the physio who fitted my new brace for me and asked her to please burn it. I suspect she thought I was joking. I wasn’t.

What next?

At the moment, I’m not taking any pain relief during the day at all, except for icing it twice a day for at least half an hour. I take paracetamol before bed (and usually wake up almost exactly six hours later for a second dose). I’m wearing the ROM brace during the day (set at 0-90°, which will remain for six weeks, this is a condition of the meniscus repair. I’m really only able to move about 0-40° right now, but physio will help with that), and a splint from my original injury that doesn’t have that nasty foam strip in it overnight for comfort, with a compression stocking for swelling. I can sleep on my left side, with the injured leg straight out, and my other leg in front of it, but can’t sleep on my right side in the same position (with a pillow under my injured knee) for very long before it hurts, although this is improving. Dr Davies tells me this is because he moved around a lot of stuff on the right side of my knee, so it’s more tender there. My appetite is not quite back to normal, but it’s definitely improving. I start physio tomorrow and will keep going once or twice a week until I’m off crutches at least. I’m moving around well now, and even managed to cook a meal for dinner last night, so everything is starting to go back to normal, except I still make a cup of tea in a thermos so I can carry it to wherever I want to sit! Only four weeks on crutches to go …

by Loquacity on August 01, 2017 01:44 AM

July 30, 2017

Anne Gentle Anne Gentle

Author of Conversation and Community: the Social Web for Documentation. I’m a writing fiend, technical geek, community doc nut, + Content Stacker for OpenStack.

Investigating Jekyll for versioned content

“Surely I’m overthinking this,” I kept saying to myself, impatiently waiting for a solution to appear before my eyes. I learned that it’s tough to create versioned content with a static site generator, while making sure that the source control system does the version tracking and scripts do the build automation and your theme doesn’t lose its mind.

I needed to find the best way to move our current non-versioned content in a Jekyll site to give us output that showed users versioned sites. This is an age-old problem in the technical writing world, solved over and over again. I couldn’t quite get there on my own. Eventually I consulted with my former co-worker Carolyn Van Slyck, to help me talk through solutions. She was able to show me how to copy source files at build time without checking them into Git. She also provided a valuable sounding board for “am I the crazy one?” Much gratitude to Carolyn for the help with my test repository at versions-jekyll!


I found that there are a couple of key places where the complexity arises, when using a static site generator. The first layer is within the source. When using source control system, I shouldn’t need multiple copies of content files in the repo itself. The second layer is in the output. When using static sites, I should build to a specific folder name, with the version value, each time a release occurs.

Other complexities may arise as you analyze, such as needing versioned translated content, or making sure that only certain users have access to certain releases or must login before accessing the site.

In the output I’ll still need to make sure my links work, my CSS and JS files are properly linked. I shouldn’t have to maintain copies of actual output files in my source repo because I do not want to figure out merge conflicts in HTML.

So with those general guidelines in mind, I set out. I wanted to see if what we do in OpenStack with versions using Sphinx, and what Read The Docs does with versions using Sphinx, could translate to versions and Jekyll. What I learned is that it can, but not exactly in the way I was thinking about it.

Setting a version value in the source

With Jekyll, you can get access to values by setting them in a _config.yml file, which is used to build the site each time. You can also set values in a specific config file used only for that version, and build with both the “base” _config.yml file and the versioned config file. You can also have a theme that uses a metadata value called “permalink” that sets the output folders that make up the URL for the output file. All these configuration options could be used to set the version value. Testing each option took some time.

Outputting version values into directories

With a Jekyll theme like Minimal Mistakes, you cannot build directly to the gh-pages branch, because it uses gems that are not supported by GitHub Pages. Instead, the build script in the versions-jekyll repo builds locally and copies the files to the gh-pages branch for publishing. So, the script needs to build the versions available to it locally. Right now, a “for” loop in bash does this work, so the script reads in version values.

An approach I learned was that you could pass in more than one _config.yml file at build time. With the correct configuration, Jekyll builds all the relative links to CSS and JS files needed for the theme. I did have several failed attempts while I played with permalinks, baseurl, and so on. I found this post, Configuring Jekyll for User and Project GitHub Pages with reference tables super helpful.

As versions are added, you’d need to update the script with the values, or you could read in a versions list from a file. Here’s an example for three version values to be outputted into three folders,,, and

for v in 4.1 4.2 4.3
    # Checkout a versioned branch with the version name
    git checkout $v
    # Create a configuration file that sets a new baseurl based on version
    echo "baseurl : /$v" > _config.$v.yml
    # Build using both the basic configuration file and the version config file
    bundle exec jekyll build --config _config.yml,_config.$v.yml -d _site/$v/


The version control of source is done with git through stable branches or tags. You can debate a bit about which is “better” but I believe stable branches make more sense than tags so that you can later backport any fixes to a branch sensibly.

The versions of the output are not semantically meaningful, and can have silly names if needed. Output versions can also skip a release, so the version value is treated like a string and not an integer.

The settings in the _config.yml sets the destination folder at build time for the versions. I’ve tested using both “collection” settings and “baseurl” settings and found “baseurl” to be the simplest for our theme. Your experience and theme settings may push you one way or another.

The output goes to GitHub Pages, in separate folders per release, so that the URL also reflects the version number you read on a given web page. In our case, we build locally, then push to the gh-pages branch from that local build.

The master branch always reflects the current, or latest, version of the docs site. I’ve chosen to use /latest/ in the output URL but you may have reasons for naming it in another way. For example, you may not want to always publish master to a public site, and instead need to publish from a stable version only.

Minimal Mistakes is the theme in use, for us, which supports collections. The permalinks are encoded in the markdown files themselves, but those are not in use when versioning docs when using the baseurl approach, so the collections remain intact and unchanged for our solution.

Design decisions

On the front-end, you’d still need to design for scenarios such as “What if the page I want to access on version 4.1.1 does not exist in version 4.1.1? Do you give a 404 error or a special “not found” page when navigating versions? What about an archived version, can someone still find it and browse it?

Also, if your product provides n.n.n release versions, but really the docs site only changes drastically at n.n release versions, you could version the source files at n.n.n but only output content at n.n releases. This design decision would make the docs simpler to navigate, but may cause confusion if a user looks for the site versioned at n.n.n.

I’ve also not discussed the problem of search scope here. The design decision here is whether to enable searching across all releases? Or scope the search to only one release at a time?


Testing different solutions took weeks of time. I wanted to have confidence in the maintainability and design of our solution. I also had several weeks of diving into complexity before resurfacing and seeing the baseurl solution was in front of me the whole time.

So when I went to try out the “fake” install guide in the versions-jekyll repo, I built the site, went to the site url, and entered a version number and install-guide/ in the browser URL. But, there’s no such file as an index.html file in /install-guide/ because the only files are named and So I add an, but in fact, Jekyll won’t give me a URL like, even when I put it in the permalink metadata to be /install-guide/ in an /install-guide/ file. Why not? I guess it’s because Jekyll wants to ensure the permalink settings are for the same depth across the site? This confusion caused me to look for an even simpler solution.


For our Jekyll docs, changing the baseurl for the entire site as a version value became the simplest solution. I investigated collections for versions quite deeply, but wasn’t happy with needing to change so many permalinks each build, and the risk of broken links seemed higher. Fortunately, our layers of complexity are minimized, in that we only have a few deliverables, our site’s content is not translated, and we do not need to require logins on the content.

References and further reading

by annegentle on July 30, 2017 03:54 PM


  • Anne GentleAnne Gentle Author of Conversation and Community: the Social Web for Documentation. I’m a writing fiend, technical geek, community doc nut, + Content Stacker for OpenStack.
  • Jim CampbellJim Campbell HRIS admin to the stars, and documentation writer for needy open-source projects. As a Chicagoan, I also know enough to not put ketchup on a hot dog.
  • Lana BrindleyLana Brindley Writes too much, reads too much, talks too much, thinks too much, drinks too much. Generally superlative.
  • Shaun McCanceShaun McCance GNOME documentation team lead. Programmer. Technical writer. XML expert. Community leader. Free software enthusiast.