Topic Based Writing

Users Read Topics Not Full Documents

The days of the printed manual as an accessory of most products are numbered.

Yes, some products will still have printed manuals, but technology is quickly removing the need for many people to read that printed document that is included in most products you buy.

Manuals contain very useful information. Like how to install a new washing machine or how to troubleshooting common errors when they occur as they will most likely do.

But, increasingly, users, and I speak from experience, are not consulting that printed manual and instead, are searching online when they need help. Why?

Manuals (despite the best efforts) are still difficult to read
Manuals once shipped, can not be updated even when operation errors pop up with products.
Changing habits. Because of the proliferation of the internet, many users now rely on search engines to find the information they need. Even when they already have access to that very information in the very manual that arrived with their new washing machine.

These two points are related (kind of).

When you buy a washing machine, you know why you need it. You know what it needs to function. But sometimes, you do not know how to remove something small, like the safety bolts, to make it functional .

This information is in the printed manual that comes with the machine. But you do not know on what page it is located and you need to quickly remove the bolts so that you can do your laundry.

What do you do next?

In the past, you would have relied on a technician to install the machine for you and you would not bother with the the bolts.

These days, however, machine installation will cost you some money and many people feel confident enough to install the machine themselves. Its not rocket science after all.

In the past, people with a DIY attitude would read the manual, and find the paragraph on how to safely remove the bolts.

These days habits have changed. People with a DIY attitude will not read the manual. Instead they will rely on search engines for information on how to safely remove the bolts. And they will removed the bolts and get their machine working in no time.

That is where topic based writing or authoring comes in:

The topic is usually limited in scope (to a procedure)
It has a limited outcome (removal of safety bolts)
It assumes the user has some knowledge and the tools to accomplish the task.

These topics are all over the internet and for a purpose. People rely on them to accomplish tasks every day.

That is why topic-based writing is very important in technical writing. It is the present and the future.

Users no longer have the patience to read through manuals looking for what they want to do. They want to do the task immediately.

Topic-based authoring makes the content:

Faster to access
Easier to read and share (unlike content in manuals)
This results in faster task completion, happy users, and successful businesses.

The assignment

This project was an MA class assignment.

Audience: Postgraduate students
Responsibilities: Instructional Design, E-Learning Development, Document Design
Tools Used: Sulis wiki dev tool, XML

See the full project

The lecturer asked the student on the MA program to chose a topic from a list. The topic had to be:

A procedure
A reference
A concept

The topic also had to be relevant for technical communication students who were the target audience while conforming to the seven characteristics listed in Mark Baker's book Every Page is Page One.

Students were required to add relevant metadata to their creation.

The challenges

I had not used XML (extensible markup language) before and this was learning on the job for me.
I had not used the wiki tool before and the instruction for use were contained in a short video posted on panopto.
Each student had to chose only one topic and sign up for it on it on a shared list.

The process

I signed up for my topic and started work. I had access to a discussion forum where students would share challenges encountered and how to resolve them.

Collectively we were working on an evolving document in real time. Our several topics would form a wiki accessible to future students. Some students were working in different time zones and we had a deadline for submission of the assignment.

There was a risk of another student accidentally editing or deleting another student's topic.
There were reports of students losing work because they had not saved their work.
There were issues with embedding images.

Students with more working knowledge of XML offered solutions to most if not all the issues that arose.

I was able to accomplish the assignment in time and without glitches and I am very happy with the grade.

Takeaways

I found this kind of collaborative work interesting. It is common with most remote working and I was glad to have experienced it as a student. I now have a good idea of what it takes to work remotely as an individual and a member of a team on a collective project.

I was using XML for the first time and I do not think my zero prior knowledge was inhibiting. I loved it and challenged myself to seek more knowledge of mark up languages.

See the full project