Sarah’s hevvy fruitcake

It’s that fruitcake time of year. I made one that was a bit of an experiment and it worked rather well. What’s more, it’s gluten free. Here’s the recipe, for those adventurous souls who want to try it.

Sarah's hevvy fruitcakeNote: Baking is an imprecise art, and so is this recipe. It’s a little like technical writing. ūüėČ Oh, and the spelling of “hevvy” is intentional.

Oven temperature:¬†180¬į C (360¬į F).

Baking time: 60 minutes.

Baking pan: Round. Diameter 23 cm (10 inches), height 6 cm (2.5 inches).

Baking paper to line the pan.

Ingredients

Cake:

  • 225 g (8 oz) brown sugar – the darker the better. I used dark muscovado unrefined cane sugar.
  • 225 g (8 oz) margerine or butter – I used margerine.
  • 4 eggs.
  • 400 g (12 oz) cake flour – I used gluten free flour.
  • 1 teaspoon nutmeg.
  • 1 teaspoon cinnamon.
  • Half a teaspoon mixed spices.
  • Pinch of salt.
  • 200 g (7 oz) sultanas.
  • 200 g (7 oz) blackberries or some other squishy, slightly sour berry – I used frozen blackberries.
  • 2 handfuls pecan nuts – basically, as many as you want.
  • 1 teaspoon vanilla essence.
  • 50 ml (2 tablespoons) molasses.
  • 50 ml (2 tablespoons) or more plain yoghurt (if necessary, make sure it’s gluten free).

Topping:

  • 6 tablespoons brown sugar – but have more available, because the topping is tricky.
  • 50 ml water.

Method

A slice of hevvy fruitcake looks like this:

hevvy-cake-slice

Cake

Mix the margerine/butter and sugar. Add the eggs one at a time, mixing each egg in well.

Add the¬†flour, nutmeg, cinnamon, mixed spices and salt. Here’s a tip to prevent flour from flying everywhere: Use a wooden spoon to mix the dry ingredients at first, then use an electric mixer to finish the job.

Chop the pecan nuts into largish pieces – quarters or thirds of a nut are good.

If you’ve been using an electric mixer, now’s a good time to abandon¬†it.

Add the sultanas, blackberries, and chopped nuts to your mixture. Also add the vanilla essence, molasses and yoghurt.

Mix it all together¬†with a wooden spoon. Don’t worry about getting everything 100% mixed in. It’s fine if there are still a few visible globs of yoghurt when you’ve finished.

Baking

Line the baking pan¬†with baking paper. Spoon the mix into the pan, ensuring a more or less level surface. Bake for approximately an hour at 180¬į C (360¬į F).

Stick a thin knife into the cake to check it after about 40 minutes, and then again every 15 minutes or so, to see how it’s doing. When you pull out the knife, the blade shouldn’t be completely clean (it’s better if the cake is moist). It should have some moist, slightly gooey stuff on it, but not a lot of uncooked dough.

Remove the cake from the pan and put it on a metal rack to cool. Leave the baking paper on the cake until it’s cool.

Topping of caramelised sugar

The aim here is to heat the sugar and water until the sugar caramelises, then pour it onto the cake before it sets hard.

Set a pot of cool water ready, for testing your caramel mixture. (Cold water from the tap is fine.)

Put the sugar and water into a small saucepan and bring to the boil on a high heat, stirring continuously with a wooden spoon. At first, the sugar mixture is thin with lots of small bubbles. Keep it boiling and keep stirring. The sugar mixture gets thicker and darker.

Now it’s time to test the mixture. Take your¬†wooden spoon out of the pot and hold it over your separate pot of cool water. Let a drop of the sugar mixture fall into the water. Prod the drop with your finger – it should be hard to the touch. If it’s still squishy, or if it disperses and flattens when you drop it into the water, then the caramel mixture isn’t yet ready.

When ready, dribble the caramel mixture over the top of the cake. Don’t worry if it’s not evenly spread – there’s no need to cover the whole cake, and it’s fine to have deep and shallow valleys of sugar.

Here’s another tip: ¬†If the sugar crystalises in the pan, it’s not hard to wash, despite the scary appearance of the caramel-encrusted pan. This means you can quickly start again with another mixture of sugar and water if things go wrong the first time.

Enjoy the cake!

Modern technical writing, a talk by Andrew Etter about his book

Yesterday I attended a Write the Docs meetup where Andrew Etter spoke about his recently published book, Modern Technical Writing: An Introduction to Software Documentation.

I haven’t read Andrew’s book yet, so I appreciated this introduction from the author. One thing that strikes me is how interwoven are two aspects of technical writing: firstly, the processes (the way we glean our material and our efficiency and efficacy in writing content); secondly, the tools we use. Every now and then, I’ve heard people say we shouldn’t focus so much on the tools when discussing our profession and how best to perform our role. I’ve thought that too, at times. But it seems to me that these two aspects of our work are becoming more and more interdependent. The tools make a specific way of working possible, and the way we think of our work determines the tools we choose.

From what¬†Andrew said¬†about his book yesterday, the content of the book seems to agree with my above musings. Now, I should go and read that book. ūüôā

Modern Technical Writing, the book

Andrew pointed out that you can read his book in about 45 minutes, and that he’s been allotted an hour for this talk! This comment raised a good laugh.

The book is about 11,000 words. Andrew summed it up (with a smile) in about 12 words, which roughly correspond to the highlighted words in the list below:

  • Learn – learn your subject matter and get to know your audience.
  • Write in lightweight markup – it’s the easiest way to get from a pleasant writing experience to a useful website. Markdown is a good solution, because people want to use it. You’ll therefore have plenty¬†of people willing to contribute to your docs.
  • Treat the docs as code – version control and continuous updates. The stability of the docs over time depends on the quality of your updates.
  • Create static websites.

The¬†book, Modern Technical Writing, started as a wiki page. Andrew¬†needed information about technical writing to pass on to others. He did a bit of research, to see if anything already existed that he could use. Having found nothing that fit the bill, he decided “I’m the writer”, and wrote it himself.

What makes a book sell?

Andrew spoke amusingly about an FAQ on the Kindle Direct Publishing site: “Why am I not selling? I am a good writer.” The fundamental question is, how do you get people to buy something you’re selling? Andrew said with a smile that he has no idea!¬†He doesn’t do much marketing or promotion via social media. Here’s his¬†recommendation:

If you have something you feel strongly about, something you’ve shown to your friends and got good feedback on, something you think adds value to the world, then put it out there.

The publishing process

Andrew chose Kindle Direct Publishing as the mechanism for publishing and earning royalties. The rules around pricing are really complicated. The magic happens when you upload your book to Amazon, and they transform it to a Kindle book. Amazon is the market leader in online publication, and your book benefits from this.

One drawback is that you cannot test your book before publication. You just upload it, view the highly inaccurate preview, and then publish it.

The aftermath

Andrew showed us a screenshot of his book on Amazon right next to Strunk and White’s Elements of Style.¬†To be near Elements of Style is mind-boggling. But it lasted a very short time. He ¬†dispelled any myths that self-publishing is lucrative. He has, however, received very nice messages from people all over the world.

Charging a price for the book

If you give something away for free, there’s the perception that it’s not really valuable. If you give it a price, people are more likely to see it as worth something.

For his book, Andrew thinks that the price of around $4 is in the right range.

What technical writers do

What is the¬†“differentiated value add” of a technical writer? That is, what do we do that no-one else does?

  • Consistency – specifically, consistency in tooling. Without tech writers, each engineering team would pick their own tools, which would result in chaos.
  • Accountability – someone has to be responsible for creating good documentation. Andrew remarked with a smile that you have to be able to fire someone if the documentation is bad.
  • Creation and curation – writers review and take care of others’ content as well as writing it.
  • Culture – having good writers around makes everyone else aware of what good writing looks like.
  • Good documentation leads to efficiency improvements in many ways. It helps the organisation and customers save time, and time is a precious resource.

Andrew talked a bit about the writing process, project prioritisation, and the team. He joked at the beginning of the presentation that these topics may form part of the second edition of the book, if he ever considers writing one.

The old way versus the new way of producing documentation

Andrew talked about old methodologies and tools versus the new ones, and walked through some code samples. I didn’t make notes of this part of the talk. The details are¬†in Andrew’s book.

Conclusion

Thanks to Andrew Etter for an engaging presentation and congrats on your successful book!

Where do technical writers fit in an organisation

Where do technical writers belong in an organisation? Which team should we be part of? This is an interesting question that many of us are asking. I don’t have an answer. In fact, there are probably as many answers as there are possibilities, because each organisation is different, and so is each technical writing role. But I do have some musings and two presentations to introduce.

Where we end up in the organisation can affect the way other people see us and our contribution to the company. It can affect our own perception of our purpose and goals. It may even affect our ability to do our job, if our position in the company determines the access we have to information, technology, and other resources.

Sometimes, we’re lucky enough to have a say in where we end up. That’s when it becomes really interesting, because the choice may not be easy.

Where do we belong?

Here are some of the possibilities:

  • Engineering and product management: Technical writers work closely with the software developers to understand the ins and outs of the product. It’s also very useful if technical writers can give early input into the design of a product, taking advantage of the user-focused nature of a technical writer’s role.
  • User experience: Technical writers, UX designers and UX researchers are focused on the needs of the customer. They often work closely together in producing the documentation and other user aids, even if they’re not part of the same team.
  • Support: The documentation is an essential resource for the support team. Working as part of support can give technical writers direct access to the requests and problems reported by customers.
  • Marketing: The documentation is an important marketing asset, and the level of technical detail in the documentation tends to yield excellent SEO (search engine optimisation). Technical writers and marketers often find themselves writing about the same products and topics, especially at the launch of¬†a new product or feature. Marketing teams have great resources for customer analysis, and a flair for¬†words.
  • Developer relations: This is a team of people with various roles, including technical writers, software engineers, developer advocates, marketing leads, and others. The team acts as an interface between the internal teams who’re developing the products, and external developers/customers who’re using the products. The products are developer-focused, including APIs, SDKs, libraries, and so on.
  • Change management: See the comments on this post for discussion.
  • Any more?

Two takes on working with product teams

Recently I presented a webinar on working with an engineering team, and I attended a talk by Craig Simms on integrating more closely with a product team. It’s interesting to compare these two takes on the topic.

Webinar: Working with an Engineering Team

The ASTC (Australian Society for Technical Communication) and I recently collaborated to host a webinar on working with an engineering team. You can watch the recording below, and on Vimeo. The slides are available on SlideShare.

Click the play button to view the video above.

Talk: Integrating with Software Product Teams

At a recent Write the Docs meeting,¬†Craig Simms¬†presented a talk on how technical writers can integrate more closely with software teams. It’s a zestful¬†account of the journey he and his colleague have taken towards becoming integrated with a product team, and the lessons learned¬†during that journey. The recording is on YouTube, and embedded below.

What do you think?

Where do technical writers fit in, and do you know of any other presentations that talk about integrating with various teams?

Report from Write the Docs Sydney

This week we hosted the first ever Write the Docs meetup in Sydney. It was great to see so many familiar faces and to meet so many new people too.

The Sydney meetup is part of the Write the Docs Australia group, founded by Swapnil Ogale. This was the Australia-wide group’s second meeting, after the kickoff in Melbourne in September.

The Sydney meetup

We had 22 attendees at the inaugural Sydney meetup. The venue was the Google offices in Pyrmont.

Write the Docs Sydney

Swapnil was an excellent host. Between the two presentations (see below) he asked attendees to introduce themselves and say what they liked most about technical documentation or being a technical writer.

What attendees like about technical documentation / technical writing:

  • I like to¬†explain things.
  • The scope of technical documentation extends¬†all the way from consumers to developers.

Write the Docs Australia

  • I like editing a doc when someone complains about it – that means they need it.
  • I like to help things go smoothly.
  • I’m married to a technical writer.

Write the Docs Australia

  • Technical documentation says exactly what it means. It cuts out all the fluff, even when describing an error in the product.
  • I get to do problem solving in a creative environment.
  • I like the ability to make the documentation¬†a tool that someone can use rather than just read.
  • Technical documentation captures stuff before it’s lost.
  • I truly enjoy the research that goes in before writing the docs. Discovering bugs!

Presentation: Integrating more closely with software product teams

Craig Simms, from Campaign Monitor, presented a talk on how technical writers can integrate more closely with software teams. Campaign Monitor works off an agile development process. As processes change, the technical writing team must change to keep up.

Craig’s presentation was amusing and engaging. He told the story of how technical writing started at Campaign Monitor¬†as a community building role, but it quickly became apparent that it was¬†a core technical writing role. Quite quickly, the two writers in the company felt that their role description and placement in the company didn’t reflect the value that technical writers¬†bring to an organisation. They decided they¬†needed to join a product team.

Craig Simms, Campaign Monitor

Craig described the two years of adventure he and his co-writer have had, attempting to get into a product team. They’ve not¬†yet succeeded, Craig said with a laugh, but he gave a zestful¬†account of the lessons learned, and the steps they’ve taken¬†towards that¬†goal. One of the questions that’s arisen is this:¬†Is product the right place for technical writers? An attractive alternative is to be part of the marketing team.

This quotation from Craig’s presentation in particular rang true with me:

Define your own value, and never stop telling people.

Here’s¬†the recording of Craig’s presentation:

Presentation: Wrapup of Write the Docs Prague

Swapnil Ogale presented his summary and take-aways from the recent Write the Docs Prague conference.

Swapnil Ogale, Write the Docs

Swapnil talked about these topics:

  • Why he attended the Prague conference.
  • Attendee demographics – he showed a lovely picture of the venue and participants.
  • Range of topics covered – wide, including fiction and health!
  • A deep dive into 2 presentations he found most useful.
  • The unconference part of the event – spontaneous sessions on what people wanted to talk about.
  • Key takeaways from the conference.

An interesting statistic:

70% of participants are working on dev docs, APIs and UI text.

Here’s the recording of Swapnil’s presentation:

Where next for Write the Docs Australia?

I’ve been lucky enough to attend both meetings of the Write the Docs Australia group. Perhaps I can keep a good thing going and join the third, wherever it may be. Brisbane, anyone? ūüôā

Sharing now in Tech Comm on a Map on Android

I’ve released an update to the Tech Comm on a Map app on Android. You can now share¬†a link to the location of an event via email, chat, Twitter, Slack, and so on – any app on your Android device that shows up in the standard app chooser. The people you’ve shared the link with can use it to open the¬†Tech Comm on a Map¬†website directly at that location. Handy for sharing event information!

Tech Comm on a Map puts technical communication titbits onto an interactive map, together with the data and functionality provided by Google Maps. You can use it on the website and get the Android app.

New: link sharing

Let’s say you’re looking at the tech comm events in your city, or in a part of the world you’re planning to visit. You want to let a friend or colleague know what’s happening in the tech comm world. Now you can share a link to a specific location on the Tech Comm map.

In the Android app, view an event:

Tech Comm on a Map on Android

Pull up the event panel from the bottom of the screen, to see the event details. Notice the new Share button:

Share button on Tech Comm on a Map

Click the¬†Share button. Android pops up a standard app chooser, showing you all the apps on your device that can handle the share request. It looks something like this, but you’ll see a different selection of apps:

Android app chooser

Choose an app. Tech Comm on a Map sends your chosen app a bit of text and a shortened URL. This screenshot shows Twitter as the chosen app:

Shared link from Tech Comm on a Map

Your friends can copy the link and paste it into a web browser, to open Tech Comm on a Map at the location you’ve shared. (In this case, the shared link is¬†https://goo.gl/SjBvRc.)

What’s next for Tech Comm on a Map?

Currently, the shared link opens the Tech Comm on a Map webapp. It’d be great to¬†offer a link that opens the Android app directly at the given location.

The way to do it is via Android intents. I got part of the way to achieving this in the current release. If you click a link of a specific format, the Tech Comm on a Map Android app opens, but it doesn’t open at the given location. So far, I can’t get the location parameters to go all the way through to the app.

There are some other nice tweaks I could add to the app. I’m keeping track of feature requests and bug reports on the GitHub issue tracker. See the issues for the web app and for the Android app. They’re both open source, and you’re welcome to get involved.

%d bloggers like this: