I’m starting out on a new role. Still a technical writer, still at the same company, but on a new product, working with a new group of people and a new set of docs. Here are some of my thoughts on getting started in a complex new field.
I’m reading everything I can about my new field, and watching the videos that’ll help me figure out what it’s about. As a technical writer, I’ll soon be immersed in both the technical and the theoretical side of the field. But before that immersion happens, it’s good to find out how people out there in the world are using the technology. The applications where they’re putting it to use. The functions they expect it to perform.
In my case, the new field is machine learning. That’s a big change from my previous role, documenting maps APIs. I loved working on the maps APIs, and now I’m super excited to learn something new.
Noting the new concepts and terminology
As I read articles and watch videos, I’m making notes of the things that puzzle me or are new to me: concepts, terms, methodologies, technologies. These notes may become part of the docs I write, or they may turn out to be useful only to me. They’re valuable, because I’m currently acting as a first-time reader in the field. Later I’ll forget what I didn’t know. It’ll be harder to put myself in a newbie’s shoes.
For example, watching this video about machine learning, I found I needed a new definition of the term “vector”. The video used the term in a way that was unfamiliar to me. I found some help on Stack Overflow. (It turns out that, in simple terms, a vector in machine learning is a series of values, which you can think of as a row in a table.) I made a note of the term and its meaning, in case I decide to add a glossary in the docs.
Discovering the audience
At this time, I didn’t have a good feel for the intended audience. Perhaps the intended audience for the documentation would already know the term that I hadn’t understood. But it did no harm to make a note. In fact, it helped solidify my own understanding of the term.
While reading, I’m looking to get a feel for the various types of audience in the field. This will help me narrow down the audience for the docs. What types of experts are there out in the world? In the case of machine learning, there’s a diverse audience, all the way from machine learning scientists who design the training/inference models, through data scientists who know all about data and want to try machine learning as a new way of gaining insights from the data, and application programmers who don’t know anything about machine learning and just want to use a specific application of it in their app.
Figuring out the workflow
When I first started learning the field, I didn’t look at my own organisation’s existing docs for this range of products. Instead, I immersed myself in what the world out there is doing. What’s the typical workflow that people are talking about and trying to implement? Later, I’ll look at how our own products fit into that workflow, and how our docs explain the flow.
Remembering that things change fast in technology
If you’re moving to a new project with an existing doc set, take into account that things were probably different when the doc set was created. Perhaps the audience has moved on since the early days in that particular field. Perhaps most of your readers now know more about the topic than they did when the docs were written. This is particularly relevant if the technology was new when the docs were written.
Perhaps the readers are using a different set of terminology now. People may have standardised on terms, while it’s possible the docs have not kept up.
As a new reader of the docs and a new entrant into the field, you’re in the best position to notice this kind of thing.
Something I learned while writing this post: newbie versus nooby
There’s a difference between a nooby and a newbie. I didn’t know that. I thought it was just a spelling difference. In fact, there are three terms: noob (or n00b), nooby, and newbie. A noob is a rather naive, some would say even stupid, person. This term is used particulary in the world of games. Nooby is an adjective referring to the type of (silly/annoying) thing a noob would do. A newbie is someone who is new to the field or area under discussion. It seems you don’t really want to be called a noob, whereas being a newbie is not a bad thing. At least newbies can spell!
Release notes, sometimes called a changelog, let customers know when something’s happened in or to a product that could affect them. Various groups of people are involved in creating the release notes. Sometimes it’s hard to know what to include in the release notes. Here are some thoughts from me, after writing release notes for different types of products over the last few years.
The most important function of release notes is to let customers know that something has changed in the product, particularly when that something may affect the way the customer uses the product. The change may be a new feature in the product, an entirely new product, a change to the way the product works, a change to the way the customer uses the product, the removal of a feature, or even the deprecation of the entire product.
Examples of release notes
Atlassian creates comprehensive release notes for the major releases of each product, with graphics to illustrate the major features. For example, take a look at the Confluence 6.0 release notes. The minor releases list the issues resolved.
The Canvas release notes are full of information, including graphics to illustrate the top updates.
Release notes at their most minimalist are often called a changelog. A good example is the page for the Google Maps Android API. For a major release, the team includes screenshots and a tutorial on the Google Maps APIs Blog as well as in the documentation.
Some products support a complex set of variations in platforms and languages, as you can see in the Debian release notes.
Chrome DevTools kick off their release notes with a video and plenty of graphics.
Who writes the release notes?
Often, a technical writer creates the release notes based on input from product managers, engineering teams, marketing advisers, and other stakeholders.
In other cases, a various teams write or contribute to the release notes. For example:
- The engineering team may write the simpler release notes, such as minor releases (point releases) consisting of bug fixes.
- Product managers or marketing managers create the content for major new features or product launches. This is particularly so if the organisation’s primary promotion channel is a blog. A case in point is the Google Maps APIs Blog, which I mentioned earlier in this post.
- A developer relations team may write software samples that illustrate a new feature in an API, and a video illustrating the new capabilities.
Letting customers know about the release notes
It’s a good idea to ask how customers will discover your release notes. It’s unlikely they’ll come and check your site regularly, just to see if something’s happened.
Here are some of the ways you can let customers know that you’ve published new release notes:
- Write a blog post about major updates and other happenings that your customers need to know about.
- Offer email subscriptions for your release notes and other product news.
- Set up social media accounts for your organisation, and announce product news via those accounts. This tactic is useful if you know where your customers are likely to see the news. Examples are Twitter, Facebook, Reddit, Instagram, and more. For an example of indepth use of a particular platform, take a look at my post on using Twitter as medium for release notes.
An important point is to make sure there are links to the technical documentation from the release notes, blog, Twitter, and so on. The links help customers find the information they need after reading an overview of the new features/products. The links also boost the search engine optimisation (SEO) of the documentation, and let the customers know the docs exist as a good source of information.
What to include in the release notes
New features and products. Let people know about new features that enhance their use of the product. Provide an information-rich summary of what the feature means to the user, and how they can start using it. An illustration is good idea. Depending on the product, the illustration could be a screenshot, a photograph or video, a diagram, or a code sample. Also include a link to the documentation where people can find more information. If the feature was requested by customers and the feature request is publicly visible, link to it so people can see you’re listening to their requests.
Bug fixes. Include a list of the issues fixed in this release. Link to the documentation for further information where relevant. If the bug report is publicly visible, link to it so people can see you’re responding to their reports of problems.
Upgrade guide. Note any steps people need to take when moving from the older release to the newer release of the product. In some cases, there may be significant steps required. The nature of those steps depends on the type of product. For example, if the product is an API, the developers using the API may need to change their code. If the product is a software application, the system administrators may need to adjust configurations and update other applications that interface with or integrate into the updated application.
Deprecations and turn downs. Highlight any product and feature deprecations, and let people know when a product is turned down for good. A deprecation is a notice to customers that a feature or product is no longer recommended for use, and will or may be taken down at some point in the future. If there’s an alternative product or feature, let customers know where to find information about it. If possible, provide a migration guide telling people how to move from the deprecated feature to the new feature.
Other notes. Put yourself in the shoes of the user, and add the information you’d find useful. These notes may come from UX testing of the new feature, internal testing of the upgrade process, knowledge of customers’ procedures from the technical support engineers, or other sources.
Is a template useful for the release notes?
You could consider creating a template, to ensure that each update to the release notes follows a common pattern. Often though, the previous set of release notes is a good enough guide.
A template may also be a good idea for collecting information from stakeholders, but beware the content bloat that happens when people feel they need to supply words to fill a gap. Release notes should be lean and information rich.
That’s about all I can come up with for now. Do you have any thoughts?
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.
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!
The first book of my new Trilby Trench series is now available on Amazon.com as a Kindle ebook and in paperback form. Trilby Trench is an action hero who also happens to be a technical writer. She’s deft with words, analytic in thought, and skilled in everything that she’s written about. That covers a lot of ground. Things happen to Trilby, and she happens right back at them.
The book title is A Word If You Please. You can get it here:
- Amazon.com: Kindle ebook (USD $3.11) and paperback (USD $6.99)
- Online book on the Trilby Trench site (free of charge)
I first published A Word If You Please in serial form, chapter by chapter, on the Trilby Trench site. Last week I went through the very interesting process of publishing the book with Kindle Direct Publishing, both as a Kindle book and in paperback.
If you order quickly, you just may see the paperback before I do. 🙂 I’ve ordered one, but it hasn’t arrived yet. It has to make its way from the US all the way to Australia. So I have no idea what it looks like in real life, or what it feels like to hold.
If you’ve read the book and are happy to put a review on Amazon, that’d be awesome!