Blog Archives

Publishing a paperback on Kindle Direct Publishing

The printed copy of my book has arrived! That’s a good reason to talk about publishing a paperback via Amazon’s Kindle Direct Publishing.

First, the long-awaited arrival of a printed copy of my book, A Word If You Please. I published the book on Amazon.com in Kindle and paperback formats. Being all the way down here in Australia, it was a couple of weeks before my hard copy arrived. And now, here it is:

  

It’s about an action hero, Trilby Trench, who also happens to be a technical writer. Does her way with words bring the danger to her or does it save her from further troubles? Only Trilby can tell you that.

Publishing a paperback on KDP

It’s been a while since I last ventured into the online tools provided by Kindle Direct Publishing. I’ve previously published two novels in Kindle format.

It was a very pleasant surprise that you can now create and publish a paperback version of your book. When I last published via Kindle Direct Publishing, only the Kindle format was available. The cost model for the paperback format is print on demand: You pay Amazon a fee for each copy that someone buys.

I loved the online cover designer. You can choose your design from a range of templates. There are different templates for Kindle ebook and paperback. Upload your image, customise the colours and fonts, and submit the design.

Only one thing didn’t work quite as expected. When you publish both a Kindle version and a paperback version of the same book, they start off as separate books on Amazon.com. It’s a good idea to get them linked, so people looking at the book online can see that both formats are available. The linking is supposed to happen automatically, based on identical title, author, and some other metadata. The auto-linkage didn’t happen for me, so I contacted the Kindle Direct Publishing help desk. They replied to my request within a few hours, and the update came through within 24 hours. Excellent service!

It’s worth spending some time reading the Kindle Direct Publishing documentation, to figure out how to upload and format your content. I decided to use straight HTML for the paperback version of my book. If you go that route, you may find this article useful: How to make an Amazon Kindle book using HTML and CSS. The author of that blog post has recently posted a disclaimer saying the post is out of date. Even so, I found the overview useful, and the downloadable set of sample files too.

Advertisements

Publishing a book online in serial form

I’ve recently published a fiction book, first in serial form on my own website, then as an entire book on Amazon.com. Publishing the book in serial form, chapter by chapter, was an interesting experience. It was an experiment. I wanted to see the pros and cons from an author’s point of view and from a reader’s point of view.

The book is A Word If You Please, featuring Trilby Trench and a collection of friends and foes. Trilby Trench is a technical writer who likes a bit of action. As Trilby’s friends know, adventure stalks Trilby and she stalks it right back. The serialised book is online on the Trilby Trench site (free of charge). You can also download the book from Amazon.com as a Kindle ebook (USD $3.11) and a paperback (USD $6.99).

Why serialise a book?

I’d been wondering about publishing in serial form for a while. What would it be like for me as author and for the people reading my book?

For example, would publishing the book in serial form be a good way of getting feedback from readers? In my case, the answer is yes. More people have sent me comments about this book than about the other fiction books I’ve published. The comments come in on Facebook, the Trilby Trench site, and other social media.

For an author, publishing a book chapter by chapter can be a challenge. Once you’ve published a chapter, you can’t go back and change it. That’d be breaking an unwritten contract with your readers. Actually, it’s a written contract, kind of! So, if your plot goes awry or you forgot to include something in an earlier chapter, you have to work around that. Before publishing the first chapter, you need a very good plan for the entire book. I like to have it mostly written, though not necessarily polished and complete.

This way of publishing made me think a lot about my readers.

What do readers think of the experience? Some may find it fun to have to wait for the next instalment. The suspense may increase their interest in the book. Others may find it annoying to have a break artificially imposed on them, or may lose the thread of the story. Perhaps a serialised book would stick in people’s memories longer than if they’d read it all in one go. Perhaps some people simply wait until all the chapters are available!

Where to publish a book in serial form?

I took a look at a few options for where and how to publish the book online.

Wattpad is an online community for readers and writers. If you publish your work there, you have a ready audience and a medium that’s well designed to bring authors and readers together. I wasn’t too sure that the primary Wattpad audience was right for my book. The most popular genres there are science fiction, young adult, and fantasy, and my book doesn’t fit into those categories. Also, Wattpad keeps popping up requests to log in, even if you’re a reader and not an author. I think that’s a barrier to entry for readers.

I also like the look of Inkitt. It has a clean UI, and it focuses on readers rather than authors.

After careful consideration, I decided to publish the book on my own blog or site, so that I could have more control.

One option was to publish the book on this blog (ffeathers.wordpress.com, where you’re reading this post). One the one hand, the focus of this blog is fiction as well as technical writing, so it’d be a good place for the book. On the other hand, this blog is primarily a blog, whereas I wanted a site that focused on the book rather than the blog posts. So, I needed a different layout, and I didn’t want to mess with ffeathers.

After weighing up the options, I decided to create a new website for the book. In fact, the website is for the character, Trilby Trench, as I plan to publish more than one book with Trilby as hero. Hence the site name and URL, trilbytrench.com. The site runs on WordPress, hosted by Bluehost. I’m using the Author theme, with some CSS tweaks to change font sizes (the default size was too small) and colours.

What do you think about serialised fiction?

If you have any comments from your experience as a reader of serial fiction, either my book or others, I’m keen to know what you think. What are the pros and cons of reading serialised fiction? Comments from authors would be interesting too!

Top writing tip – go for a walk

You know that feeling when you’ve written yourself into a corner in your blog post, presentation, thesis, or another type of document? Here’s a tip that’s helped me often to get past the corner: Go for a walk!

Take an energetic stroll. In the bush, on the beach, whatever suits you. Don’t consciously think about the problem in your document. If your brain comes up with a thought, toy with that thought in a semi-interested manner. Follow where it goes. Be open to its consequences even if they involve throwing away an entire section of your presentation, redoing some research, changing the direction of your thesis.

The thing is, your subconscious is probably right. Often, it’s bringing to the surface a feeling that you’ve had for a while. That niggling worry that something’s not quite right with the document, but you haven’t had time to go down the rabbit hole of investigation, or are perhaps too timid to follow the White Rabbit to an unknown world of randomly shrinking and expanding presentations. 🙂

While you’re on the walk, write yourself a note about your musings. Right then and there, in the bush or on the beach. I send myself emails, sometimes a series of them. A note on a scrap of paper would do too. Make sure you capture the actual words of your thoughts, because they encapsulate the insight that you’ve come to.

When you get back to your desk or your computer, save your work in its current state. Then remodel it, based on your new insights.

This happened to me recently. I’d mapped out a presentation then spent weeks working on its separate sections. A couple of days ago I read through a section I’d planned a while ago, which I’d thought would be the centre piece of the presentation. Oh no, it sounds out of place, uninspired, weird even. How can I adapt the rest of the material so this section works?

I went for a walk, watched the birds, admired the budding trees, wrote myself some emails. The end result was that I removed the worrisome section and integrated some of it into the rest of the presentation. The entire concept of the document had developed and moved beyond its erstwhile centre piece.

It’s a bit like those fictional characters who take a story in directions the author hadn’t originally designed.

Top writing tip - go for a walk

I took this picture (above) at Snoqualmie Falls, near Seattle WA.

Workshops on effective writing – technical writers adding value

Our team at Atlassian has just started presenting a series of workshops for other Atlassians, on how to write effectively. People are very appreciative of the knowledge they gain in the workshops. In turn, we technical writers learn a lot from the participants. We see how much other people value our own skills. And we get a fresh look at writing and documentation, from another viewpoint. What’s more, the workshops are fun and invigorating. Added value all round!

I’m sharing the idea and content of the workshops in this post, because we’re finding them so valuable. It’s very rewarding as a technical writer, to see how much people value our knowledge and skill. It’s also interesting to see how much they appreciate a guiding hand in what we consider the very basics of writing a technical document.

Sometimes we forget just how much we know. 🙂

The format of the workshops

Each workshop takes the form of a one-hour session:

  • Introductions.
  • Lecture – see the material below. Questions are welcome at any time.
  • Questions and wrapping up.
  • Assignment of pages and posts for the workshop participants to work on at their leisure.

Before the session, the technical writer liaises with the manager of the team about to attend the workshop. We discuss the primary focus, and find out whether the team has any current plans to write documents or blog posts. Just recently in our organisation, a number of teams have put strategic initiatives in place to write and blog more. So our workshops come at a good time.

We also ask the participants and team leads to think of documents that need writing, so that their post-workshop assignments can be real documents.

After the session, the participants complete their assignments and choose one of the available technical writers to do a review. The review is a half-hour one-on-one chat, focusing on the document and any further questions the participant may have.

Kicking off the workshop

[The next few sections in this post contain the content of the workshops. The content is on a page on our internal wiki, which the technical writers use as a basis for the workshop. Participants can also use the page as a reference after the session.]

In this session you’ll learn how to write documents that people will find, read, and get what they need from. The aim is to provide a practical guide to help you get started quickly, and to put you in touch with the technical writers who can assist with reviewing your work.

We cover two types of document:

  • A “how to” guide on the corporate intranet.
  • A blog post on the corporate external blog.

Getting started on a document

How do you write a document?
One word at a time… not!

The big picture is the important thing.

  • Sit back, think, and plan the document before you start.
  • While writing, if the words don’t come, make a note and continue writing. Preserve the big picture. Come back later to fill in the gaps.

Talking to your audience

User icon: rrobins User icon: kegan User icon: jmlemieux User icon: brollins

Who do you want to read the document? Who are the people you’re writing for, and what do they already know?

  • Think about those people carefully. Make a mental picture of a person who has the characteristics of your target audience.
  • Use that imagined person to make all decisions about your document.
  • When in doubt about wording, speak to the imagined person out loud. Write down what you said. Write it down immediately, while it’s fresh. [I usually tell an anecdote here, about how some writers stick a picture of a person on their computer monitor, and talk to that picture.]
  • If there’s more than one audience, consider writing a separate document for each audience. For example, consider separate documents for administrators and ordinary users.

The structure of a page

[The aim of this diagram is to illustrate that a page should have a number of headings, with short bits of text between them. After a quick look at the diagram, we discuss the sections in more detail below.]

Structure of a page

Structure of a page

State the purpose and audience at the top

Tell people who the document is for, and what it will help them do. This will let them know if it’s the right document for them.

Separate the concepts (“what” and “why”) from the task (“how”)

Some people already know the concepts. They’ll skip past that bit and go straight to the “how”. Other people know how to do something – they’ve found the right spot in the user interface, or found the right form on the intranet. But they want to know why they should do it, or what it means.

Use “chunking”

Split the content into easily-digestible chunks. Keep them short.

Use plenty of headings, so people can find the chunk they need. Research shows people’s eyes jump from heading to heading as they skim a page.

Lead your reader by the hand

Give clear, numbered steps. Don’t skip any steps.

People have come here because they’re stuck. Don’t worry, they’ll go away again as soon as they’ve got the idea.

Add related topics and/or next steps

Send the readers away immediately if they’re in the wrong place. After that, don’t send them away until you’re sure they’ve got what they need. So, keep links to a minimum in the main portion of the page.

  • At the top: In the section about purpose, add links to documents the reader may need instead of this one. For example, if you have separate documents for administrators and users, link from the one to the other.
  • At the end: Put related topics and next steps at the end, when you’ve finished with your reader.

Examples from our product documentation

[At this point, the workshop participants have already absorbed a lot of theory. It’s a good time to show them some examples of good and bad design. Use these examples as a discussion point. Ask the participants what is good or bad about each page.]

Good structure

https://confluence.atlassian.com/display/DOC/Deleting+or+Deactivating+Users

Good structure and design

Good structure and design

Comments:

  • Our current style is to put the related topics at the top on the right, instead of at the bottom. We’re discussing a change, because the design doesn’t work too well on mobile devices.
  • Instead of a warning macro, we’ve used a panel (uncoloured) with an exclamation icon. There’s some discussion about coloured panels, and whether people skip over them when reading a page. See the references to “banner blindness” in the resources section below.
  • [This is a good place to break for a quick chat about banner blindness. Find out what the workshop participants think about it, and how they themselves read a document.]

Not-so-good structure

[This is a page that has grown organically, with contributions from many people over a long period of time. It’s had a revamp in the latest version of our documentation. The link points to an earlier version.]

https://confluence.atlassian.com/display/CONF50/Database+Setup+for+Oracle

Unplanned structure and design

Unplanned structure and design

Comments:

  • No clear step-by-step flow.
  • No indication of what each section is for, and whether you need to do them all.
  • Other comments? [This is a good place for discussion amongst the workshop participants.]

Language and style

[This section contains a few key tips on language and style – the bread and butter of technical writers, but not necessarily well known by other people.]

Keep it short and simple

Use simple words and short sentences.

Use active voice rather than passive

[Explain the difference between active and passive. Hold a bit of a discussion here. This is a difficult concept for many people.]

Examples:

  • Passive: The chocolate was eaten by the technical writer.
  • Active: The technical writer ate the chocolate.

Why use active voice? It’s shorter. And passive voice can be confusing, because sometimes it doesn’t say who must do what. Imperative (command) is even better, when appropriate.

Bad:

“Your browser must be configured to xxx.”
Reader thinks: OK, so I’ll assume someone has already done that for me when setting up my machine.

Good:

“Configure your browser to xxx.”
Reader thinks: OK, I’ll do that now.

Clarify technical terms and abbreviations

Explain important concepts at the top of the page.

Spell out each abbreviation the first time you use it on a page. For example:

If you’re using IE (Internet Explorer), ….

…with regard to Workplace, Health and Safety (WHS).

Titles

The title is your most important tool for helping people find your document. This is especially true on a Confluence wiki, where people use the quick search a lot. The quick search is based entirely on the page title.

  • Put the key information at the beginning of the title.
  • Make the title describe the purpose of the document.

How to go about writing a page

[After quite a bit of conceptual and theoretical information, the workshop participants welcome a practical guide at this point.]

Step by step:

  1. Decide on your audience.
  2. Write the purpose.
    First write it for yourself, then refine it for the audience. This helps to form the content of the page.
  3. Write the title.
  4. Outline the document by creating the headings.
  5. Fill in the details.
    Keep each section short.
  6. If unsure, or struggling to find the right words, make a “TO DO” note and continue. Come back later.
    Hint: I use “xxxxxxxxxxxxxx” instead of “TO DO”. It’s quick to type, strangely satisfying, easy to search for, and stands out when I’m reviewing the page. [This bit often leads to some animated discussion amongst workshop participants. Some of them already do something similar. Others love the idea, and smile with delight.]
  7. Review the content yourself:
    • Have you included everything you intended to include?
    • Can you cut anything out?
    • Should you split the document?
    • Is your language and tone right for the audience?
  8. Ask someone else to review the page.
    As any writer will tell you, it’s impossible to review your own work. Your brain knows what you wanted to say, and that’s what your brain will see even if that’s not what’s written.
  9. If possible, do some user testing.
    Grab a colleague from a different department. Get a different perspective!
  10. Watch the page, and update it based on comments.

More about structure, at space level (specifically for Confluence wiki)

[It’s time for more theory.]

We’ve already talked about the structure of page. The structure of your space also important. People often need to browse to see what’s available. Perhaps they don’t know what to search for, but they do know the general area they’re in.

Scenario: Jack searches for “proxy” and finds a page. But it’s not the one he wants. So he looks at the nearby pages.

How:

  • Group related topics under a common parent.
  • Use the Documentation theme to show the space structure.

Making sure people find your page

Already discussed:

  • Structure of a wiki space
  • Page titles
  • Links to related topics

In addition to the above, let’s look at SEO (search engine optimisation) both internal (on the intranet, for the Confluence search engine) and external (on the corporate blog, for Google etc).

These are the key points for making sure people find your page or post:

  • Make the title meaningful, with important words near the beginning.
  • Make sure the URL contains real words.
    If you are blogging on Confluence, don’t use special characters like “?” in a page title, because the resulting URL will not contain words.
  • Decide the key words for your post. These are the key concepts, and the ones the people are likely to look for when searching.
  • Put your key words at the top of the post, in the introductory paragraph.
    This ties in well with our structure, where the first section contains a introduction and a summary of the story.
  • Put your key words in the headings in your post.

Tools

  • Templates and blueprints – make some of your own.
  • Use the spell checker in the browser.
  • Gliffy is great for simple diagrams.

Other hints

  • Writing is a creative process, and it keeps happening even when you think you’ve stopped!
    You’ll find yourself thinking of stuff to add to your document at odd times. While walking in the bush. Or in the middle of the night. Make a note. Email yourself. Put it on Remember The Milk. Whatever works. Such ideas are gems. Don’t lose them.
  • Optimise your page for people using mobile.
    No section and column macros (on Confluence wiki).
    Short sections with lots of headings.
  • Limit the number of note- and warning-boxes to a maximum of two per page. Using more than this can indicate an organisational problem in the text.

Writing blog posts

[This is just a summary. We have another workshop that focuses on blog posts.]

Your blog post is likely to be technical, so the process of writing it has much in common with writing a technical document.

Here are some quick pointers:

  • Maintain a character in your blog, so that people can start seeing it as a friend. Blogging is a social activity. Be yourself! Otherwise it’s difficult to maintain a consistent persona and people will soon pick it up if you don’t sound real.
  • If you’re writing on the corporate blog, ask for guidelines about the tone and style to use.
  • Write each post around a story or a ‘hook’. This will give the post a theme, making it easier for you to write and easier for people to read.
  • Make sure the title reflects the main story. This will attract readers and give you a good position in search results such as Google or Bing.
  • Add structure to the content. Yes, even in a blog post. Put headings in the post itself. Split the information into easily-readable chunks.
  • Give plenty of factual information, preferably hard-won. That’s what people value. Code samples and screenshots are great.
  • Link to other people’s blogs. If your idea is an expansion of something someone else has written, include a mention of where you got the idea. If you’ve seen someone’s post about a related topic, link to it. The other bloggers appreciate this and will start linking back to you in return.
  • Be nice, positive and sincere. If you disagree with something, say so but be constructive. Some bloggers are successful by being horrid, but to make that work you have to be really good and have a curl on your forehead. I don’t like nastiness, manipulation or one-upmanship, so I wouldn’t recommend it.

Resources

  • Kurt Vonnegut:

    Here’s my all-time favourite: Kurt Vonnegut’s How to Write With Style.

    The best thing about Kurt’s guide is that it illustrates his principles so perfectly. This excerpt is from the section called “Sound like yourself”:

    …lucky indeed is the writer who has grown up in Ireland, for the English spoken there is so amusing and musical. I myself grew up in Indianapolis, where common speech sounds like a band saw cutting galvanized tin, and employs a vocabulary as unornamental as a monkey wrench.

    This bit is pretty cool too:

    Pity the readers

  • Avoiding framed and decorated text boxes:
  • [Link to your corporate style guide here.]

That’s the end

In designing the content of the workshop, my aim was to give the participants as much practical guidance as possible in a short space of time. I picked the top things we technical writers know, about how to make a document work.

To add variety to the one-hour session, I chose a mix of theory and discussion sections. The sessions to date have been lively and interactive. We ask participants to complete a feedback form a week or so after each session.

The actual writing happens after the session, in the participants’ own time. They can then request a one-on-one review with a technical writer, before publishing their document either internally or for the whole wide world. Participants have expressed their thanks and said the content is useful, and have indicated a wish to attend a follow-up session.

What do you think of this type of workshop, and its potential as a way technical writers can add even more value to our organisations that we already do? I’d love to hear if you have run something similar within your own organisation too.

Book review – Non-Mortuus by Zola

Book coverI’ve just finished reading a new book called Non-Mortuus, by Zola. Are you a fan of vampire fiction, villains who turn out to be heroes or vice versa, and fast-paced action interspersed with thought-provoking otherworldliness? Then I think you’ll enjoy this book!

What’s it about? Vampires and vampire hunters. That seems straightforward. But the going gets a bit murky when you and the characters discover it’s hard to draw the line between undead and hunter.

It’s a good-sized book, coming in at nearly 450 pages. A good length to get you fully engaged in the characters and the world that the author sets up. And Zola has set up a very convincing world for you and the characters to make your own.

The book is full of detailed descriptions of locations, such as the streets of Lisbon in chapter 2, and the busy sidewalks of Calcutta (Kolkata) in chapter 25. I found these descriptions very interesting, and they add to the feeling that you’re in a real world.

Here I’d like to make a quick disclosure: Zola is a friend of mine. I bought the book because he wrote it. I read it with ever-growing pleasure.

The book is written in three parts, each narrated by a different character. The first is Aníbal Ferreira Silva, a trained hunter in the Order, and sworn to track down and kill the non-mortuus (vampires) of this world. The second part of the book is written in the voice of Eleanor, also known as Elle. She’s a non-mortuus. And the third narrator is Billy Ray, another of the hunters.

The author, Zola, is writing in his second language. His first is Croatian. This leads to an odd turn of phrase every now and then. It adds to the atmosphere of the book, especially in the first part where the narrator is Aníbal, who is also not English. I’d recommend a little more proof-reading to fix some grammatical and spelling errors, especially in the parts where Billy Ray, an American, is the narrator.

Billy Ray’s section is quite different in pace and style. There’s much more swash-buckling action as the book comes to its climax. I loved the characterisation in the book. Aníbal is very human in his foibles and strengths. Elle is cute though a little cold…

I recommend this book for its authoritative voice, sound theming, engaging characters, and good placement in geography and time. Zola cleverly introduces new plot elements throughout the book, with well-timed revelations about the Order and non-mortuus alike.

So, suspend your disbelief (I found that easy, right from the start) and enjoy the ride with Zola,  Aníbal, Eleanor and Billy Ray. Let me know if you survive. Mua-ha-ha…

%d bloggers like this: