In this episode of the Cherryleaf Podcast, we take a look at topic-based writing. We explore:
- What is a topic?
- Features of topics
- Why use topics?
- Why not use topics?
- Where can you use them?
- What happens if you don’t use it?
- Tools for topic-based writing
- What do you need to know
- Interacting with others
To record your questions and comments to the podcast team, use the green button:
Below is a transcript of first half of our podcast episode What’s the deal about structured content? :
Welcome to the Cherryleaf podcast. It’s February 2018, and I’m off to the London Content Strategy Meetup, where we’ll be talking about structured writing. [Rahel Bailie] I thank our sponsors Syzergy and Scroll for doing this and I want to introduce her speaker this evening who’s Ellis Pratt. I know now Ellis for many many, many years, and he’s been incredibly kind to me since. I’ll tell you the Christmas story, the famous Christmas story later. He runs Cherryleaf, and I’ll let him tell you a little bit about that side. I have a handout for the best tweet, so you can use #ContentLDN as your hashtag and we’ll will begin.
Continue reading “Transcript from What’s the deal about structured content? Part 1/2”
We’ve made a few changes to our online training courses, to make it easier to order and understand. There are now just three online courses:
We’ve moved all the other courses we had previously into a single, advanced technical communication skills course. The advanced course contains ten online modules in technical communication, and also it replaces our WriteLessons bundle.
The end user documentation writing skills for developers course is a version of our Technical Author/technical writing course.
The Technical Author/technical writing course hasn’t changed, and the classroom courses also haven’t changed.
At this month’s WriteTheDocs London meetup, Jim Fisher of Pusher presented a talk called “Don’t say Simply“. He talked about words, such as “simply”, that can seem innocuous when written in user documentation, but which show a lack of sympathy when read.
He showed how popular “simply” is with developer documentation writers, by showing the number of hits for that word in GitHub: 93 million! If you restrict the search to Markdown files (the file type on GitHub used mostly for documentation) , it’s 3,325,386 hits.
“Easy” and “easily” are also problematic, and overused: There are 4,127,104 Markdown pages on GitHub for “easy”, and 2,797,143 Markdown pages for “easily”.
The problem with “simply” and “easy” is that the related task or concept is unlikely to be always simple or easy when the reader needs to read the documentation.
These words are typically “banned” in the main technical writing style guides, but they could be appropriate in training or marketing material. In general, it’s best Technical Authors avoid them.
Here is a link to Jim’s slides: Don’t say “simply” (Write The Docs London, 2018-01-23).
Today, we’ve released our latest training course – Writing skills for developers. The course teaches developers the key skills of technical writing for software user documentation.
Although it would be better for a professional technical communicator to write the end user documentation, for some organisations, this isn’t always possible.
It is for developers who:
- Need a solid understanding of the fundamentals of technical writing
- Want to communicate more clearly and effectively
- What to know how little, or how much, they should write
- Want people to answer their own Support questions
The course comprises 14 modules in total, which delegates can complete at your own pace. The course modules are delivered over the Web in small, manageable video presentations. The course handouts and exercises are downloadable as Word or PDF files.
We can also deliver this course as a classroom course for development teams.
For more information, see: Writing skills for developers training course.
In researching what developers wanted to learn about writing documentation for users, the most common issue related to how much, or how little, they should write. One developer said:
“I would want to know what is the minimum I should write. If you can persuade me what is the necessity of each thing I’m capturing, and the voice I should use to make it most acceptable, I think I’d tune in.”
We’ll look at this question in the Writing Skills for Developers course, which we will be releasing soon. In general, you need to:
- Meet the legal requirements (which differ depending on the product, and the country).
- Provide enough information so that users don’t give up using your product, if they get stuck. For example, how to install the software, and how to get started.
- Consider the support calls, and whether you could avoid any of those by having good user documentation.
That might appear a bit too vague, so let me go back to one of the sentences above:
“If you can persuade me what is the necessity of each thing I’m capturing”
Before you start writing, you should define the purpose and audience for each deliverable you create. There should be a use case:
- Without documentation, is it clear what the user should be doing? is it clear what the user should be doing first?
- Is it clear how they should be doing the task?
- When they have to choose between options, do they have enough information to make the right decision?
- When they have completed a task, do they know what to do next?
- Are there any concepts or terms the user might not understand?
You can assess what topics to cover by doing some basic usability analysis. However, if you think about the tasks, the process (workflow), and any unfamiliar concepts, you will be on the right track.
In his newsletter last week, internet psychologist Graham Jones mentioned research that had looked into what makes some web content more shareable than others.
The researchers had analysed articles on Medium, and found there were several key factors.
One was the length of the content – around 1,800 words ( approximately 7 minutes reading time).
Another was the the “reading age”.
“The study on Medium shows that the content that gains the most engagement has a reading age of 11.”
In terms of their reading age, how old are your readers?
Graham also said:
“Typically for most business websites that I examine the reading age averages around 17 years…The Times newspaper has a reading age of 12; the Daily Mail has a reading age of 10. The reading age of the script on the 10 o’clock news is about ten as well. It is no coincidence that the world’s most popular media have low reading ages. Whatever you might think of the BBC or the Times or CNN or your favourite magazine, one thing unites them all – low reading ages. Most websites have language which is far too complicated.”
Of course, it’s not always easy to describe complicated things using simple language. We may need to describe tiny differences and modalities. However, we should aim for clear and simple language as often as possible.
A related factor was the number of words in a sentence. Graham reported the study found that the most shared content was that which had sentences that were between 12 and 15 words. This matches with best practice at places such as the Government Digital Service, where the aim is to write 11 words per sentence.
Even if your readers are much, much older than eleven, it may be a good idea to pretend they are.