Category Archives: Uncategorized

Write the Docs Portland 2018

Earlier this year I stumbled upon Write the Docs, a global community of people who care about documentation, and through its Slack channel, I have learned so much from the advice and knowledge shared by its thousands of members. The discovery has been a real godsend for someone like me who has worked independently or in small teams for most of my technical writing career.

This month I was lucky enough to go halfway across the world to the annual Write the Docs conference in Portland, Oregon to meet some of the community in person and listen to some brilliantly insightful and entertaining talks from fellow technical writers. In this post, I’ll share my highlights of the conference, my favourite bits of Portland and offer some advice on how to get there.

Conference Highlights

DISCLAIMER: I didn’t attend every single presentation but all of the talks I listened to were great. I’ve highlighted a few memorable ones below:

Kat King from Twilio, who had the unenviable task of giving the first talk of the conference, delivered an entertaining and engaging talk about how she and her team were able to quantify and improve their documentation with user feedback.

Beth Aitman from Improbable spoke about how to encourage other members of your development team to contribute to the documentation. This is something I think we all struggle with and can relate to. It’s well worth a watch:

Bob Watson gave a great talk about strategic API documentation planning, with some interesting tips about your target audience and the different types of API doc consumer  you might come across. These included the ‘Copy and Pasters’ and the ‘Bigfoot’, the rare developer who actually studies the documentation and applies the code!

As well as the main talks, there were some excellent Lightning Talks, five minute presentations given during the lunch breaks, that contained some real gems such as Mo Nishiyama’s resilience tips when dealing with Imposter Syndrome and Kayce Basque’s talk on improving response rates from feedback widgets:

If the talks aren’t your thing, there was also an Unconference where you could discuss topics such as API documentation, documentation testing, individual tools; whatever you want really. I just sat and talked with two technical writers about a documentation tool for half an hour!

Apart from the people, one of the best things about Write the Docs Portland was the venue, a striking 100-year-old ballroom with a “floating” dance floor that has played host to the likes of Jimi Hendrix, the Grateful Dead, Buffalo Springfield and James Brown. Also, if stickers are your thing then you could collect a load of stickers provided by the conference sponsors, hiring companies and Write the Docs themselves (see below):

Portland Highlights

Apart from its scenic surroundings and the views of the Tualatin Mountains, Portland has a lot to offer in the city itself. Some of my personal highlights included:

Doughnuts – Portland has a reputation for great doughnuts. We skipped the enormous queues outside Voodoo Doughnuts and went to Blue Star Donuts instead. The PB  & J with habanero pepper was pretty unusual!

Coffee – Portland has developed a thriving yet relaxed coffee culture with more than 30 coffee roasters across the city. It goes without saying that the coffee here is good! Check out Heart or Barista.

Restaurants – The food in Portland was amazing. One of my favourite meals was at Life Aquatic-themed oyster bar Jacqueline in SE Portland. For sushi check out Masu on SW 13th Ave and for a relatively cheap but delicious lunch go to Nong’s Khao Man Gai thai food cart.

Washington Park – If you want to escape the sights and sounds, head to the 412-acre Washington Park which boasts a Japanese garden, a zoo, a rose garden, an amphitheatre and lots of trees!

Powell’s Books – No trip to Portland is complete without visiting the world’s largest independent bookstore. My only advice would be to pick up a map and have some idea of what you’re looking for, otherwise you’ll find yourself wandering the many colour-coded sections and aisles for hours.

How to get there

If you live in the US or Canada, it might be slightly easier to convince your boss to fund your trip to Write the Docs. If like me, you’re based in the UK, its slightly more difficult but there are a number of options:

1. Use your training budget – Ask if you can use your training budget for the trip. It cost me my annual budget but it was well worth it and I was able to combine it with a trip to my company’s head office in San Francisco.

2. Become a speaker – I met a few writers whose company paid for them to be there because they were speakers. It’s great exposure for you, your documentation team and your company.

3. Recruitment  – If you’re company needs to grow its documentation team, you might be able to justify the cost by attending because there is a job fair and you have the opportunity to network and meet writers with a wide range of experience.

4. Exposure – Even if you don’t become a speaker, it’s a great way to raise your personal profile and that of your company. You never know when that visibility might come in handy in future.

5. Specific talks – Highlight a few specific talks from the schedule of the upcoming conference or a previous conference that may benefit you or your team. Write the Docs is a fantastic opportunity to learn from some of the best technical writers in the business!

If all else fails, see the sample email and other tips under the ‘Convince Your Manager‘ section of the Write the Docs website.

 

Advertisements

Bernard-Paul Heroux: Fact or Fiction?

If you Google for quotes about tea, one of the top hits is from the philosopher Bernard-Paul Heroux who is attributed with this quote:

There is no trouble so great or grave that cannot be much diminished by a nice cup of tea.

The philosopher’s words of wisdom about tea are quoted in articles by the Telegraph, Reuters, the Guardian and numerous blogs and websites online. An image search also shows that the Tregothnan estate in Cornwall and American retailer Trader Joe’s use the quote on their packets of tea.

This slideshow requires JavaScript.

The former journalist in me wanted to find out more about the mystery man behind the famous phrase. Searches of the name Bernard-Paul Heroux return no wikipedia listings and his name isn’t listed alongside other famous Basques or famous Basques philosophers. In fact, the only hit I got at all, aside from the quote, was that the Heroux name was a surname from the Languedoc-Rousillion region of France, a good six hour drive from Basques country. However, the Heroux surname is not listed in any online database of Basques surnames and trawling several sites of Basques births, deaths and marriages returned nothing. It’s as if Mr Heroux appeared at some point in the 1900s, made his famous quote about tea and then vanished into thin air.

Apart from the lack of evidence he ever existed, my other major doubt around the authenticity of this phrase is the fact that Basques country, as with other parts of northern Spain, has had has much more of a coffee-drinking culture for centuries. It’s just a fact, the Basques and the Spanish are traditionally coffee drinkers – not tea drinkers.

So is Bernard-Paul Heroux’s quote fact or fiction? Was he a real man or it just a figment of the imagination, dreamed up as part of an elaborate piece of marketing? I don’t want to make a storm in a teacup but until someone can prove to me otherwise, I think it’s probably the latter.

 

Debugging the word ‘Bug’

Etymology and the origin of English language have always fascinated me, partly because so many of the words we use every day represent remnants of history; artefacts left behind by the Roman Empire, the Vikings and the Norman conquest. Although words relating to computers and technology are often much younger, some are just as quirky and steeped in history as those from the past.

Like a Moth to a Flame

The origin of the word ‘bug’ in the computing world is often mistakenly credited to computer scientist Grace Hopper. The story goes that while working on the Harvard Mark II computer in 1947 she discovered a dead moth stuck in a relay. It was removed and taped into a logbook where she wrote “First actual case of a bug being found” (see picture below), which suggests that the term was already in use at that time.

H96566k

While this might have been the first literal case of ‘debugging’, there is evidence that ‘bug’ had been used in engineering for many years before that.

Scarecrows, Bugs and Bogeys

The most accepted origin of ‘bug’ is the Middle English word ‘bugge’ or ‘bogge’ (n.), which meant a scarecrow or a scary thing. One of the first iterations of the word came in John Wycliffe’s English translation of the bible (circa 1320-1382): “As a bugge either a man of raggis in a place where gourdis wexen kepith no thing, so ben her goddis of tree.” (As a scarecrow or a man of rags in a place where gourds grow guards nothing, so are their gods of wood.)

Bugs-2.png
‘Bugge’ (n) originally meant scarecrow then became an early name for bedbug.

As language evolved, another off-shoot of ‘bugge’, the scarecrow, was ‘bogey’, an evil or mischievous spirit. This gave rise to a family of other ghost and hobgoblin names including ‘bogeyman’, ‘boggart’, ‘bogle’ and ‘bugaboo’. While the archaic form of ‘bugbear’ is also another hobgoblin figure. In general these all have the same negative connotation of things to avoid and that cause fear or irritation. The direct descendant of these words is ‘bogey’ which still survives today in modern English, in aviation where a ‘bogey’ is an enemy aircraft, in golf where a ‘bogey’ is one over par (a bad score) and a ‘bogey’ (UK) or ‘booger’ (US) is a piece of nasal mucus.

giphy (1).gif

By the middle of the seventeenth century, the word ‘bug’ no longer meant scarecrow and had come to mean ‘insect’, which makes sense as many people consider them to be alien and scary. The earliest references to ‘bugs’ meaning insects often related to ‘bedbugs’, supposedly because when someone woke up covered in bedbug bites, it was as if they had been visited by something scary during the night.

Thomas Edison’s Bugs

By the 1870s, the meaning of bug had changed once more and perhaps made its first appearance in technology when American inventor Thomas Edison referred to what he called a ‘bug’ while developing a quadruplex telegraph system in 1873. He also mentioned ‘bugs’ in a letter to an associate:

“It has been just so in all of my inventions. The first step is an intuition, and comes with a burst, then difficulties arise — this thing gives out and [it is] then that “bugs” — as such little faults and difficulties are called — show themselves and months of intense watching, study and labor are requisite before commercial success or failure is certainly reached.”

They were mentioned once again in an article in the Pall Mall Gazette in 1889:

“Mr. Edison, I was informed, had been up the two previous nights discovering ‘a bug’ in his phonograph – an expression for solving a difficulty, and implying that some imaginary insect has secreted itself inside and is causing all the trouble.”

Another early example of ‘bugs’ being used to refer to technology was with the release of the first mechanical pinball machine, Baffle Ball, which was created by David Gottlieb in 1931. It was advertised with the strap-line “No bugs in this game!” (see poster below):

No-Bugs1
So it seems fair to assume that the word ‘bug’ came from ‘bugge’, the Middle English for scarecrow, which led to ‘bogey’ and all the similar words meaning an obstacle, a source of dread or something to be feared. In modern times the word ‘bug’ has become a verb meaning to vex or irritate, while the noun form has become a synonym for disease-causing germs, crazily enthusiastic or obsessive people (e.g. a firebug is a pyromaniac), concealed recording devices used by spies and perhaps, thanks to Edison, an error in technology.