Brexit – Managing the impact on your policies and procedures

No one yet knows what impact Brexit will have on how UK businesses operate. It seems very likely that the way they export will change. There is a good chance there will be forms to fill in, and other steps to complete, in order to get goods, services and people across borders. This will mean policies and procedures will need to be amended, so that staff carry out these steps in the correct way.

While we do not know yet what those changes will be, organisations can take steps today to ensure they’ll be able to change their policies and procedures documents quickly and easily. They can also start work on having information that is easy to understand and find.

This involves making sure it’s clear who is responsible for each step in the process. You may need to provide a description of the whole process as well as the individual steps themselves. You might also need staff to understand changes quickly, so web or video based content might be better than PDFs or printed manuals.  As is often the case, a modular approach to writing may be the best solution.

See also: Policies and procedures writing services

Another Masters degree course for Technical Authors to consider

In August 2016, we blogged about a new online MSc course in Technical Writing Masters degree course from Cork Institute of Technology. There is another academic course for Technical Authors to consider:  a distance-learning Master of Arts degree in Content Strategy from FH JOANNEUM.

“The programme is designed to meet the needs of working persons and is specially suitable for students who are responsible for corporate digital content in their jobs. The share of online courses is very high, and classroom teaching takes place in blocks four times each semester. Projects can be completed in the framework of your job.”

The pros

  • FH JOANNEUM has arranged for some of the world’s leading content strategist to teach some of the course modules.
  • The teaching element is essentially free to EU citizens – so there’s an incentive for UK citizens to apply in the next two years. There’s a compulsory €19.20 per term ÖH (student union) membership fee.

The cons

  • During the first three semesters, there are two attendance weeks and two attendance weekends per semester in Graz, Austria. In the fourth semester, there is one attendance week and two attendance weekends. The second attendance week in the second semester takes place on a voluntary basis as an excursion – provisionally to London.
  • The Content Strategy programme yields 30 ECTS credits per semester, i.e. 750 hours. This corresponds to a second full-time job when you complete the entire programme in your free time. You can reduce this workload in your free time by integrating projects at work into your course projects.

If you have the time available to commit to the course, then this could be worth doing.

If you want to consider non-academic options, Cherryleaf’s WriteLessons – a range of online courses in technical communication is an alternative approach.

Should you develop a comic instead of a user guide?

Page from Biological Psychology – An illustrated Survival GuideListeners to BBC Radio Four this morning heard a report that a new study by researchers at Sheffield Hallam University (SHU) discovered comics are a better educational resource than traditional textbooks.

In a related article, called How the humble comic book could become the next classroom superhero, SHU’s Paul Aleixo explained:

“We found that the use of comic books actually enables students to better remember information. Our research showed that the students that read a comic book version got more memory questions correct compared to when the same information was presented in text format alone – or in a combination of random images and text.

This shows that the way comic books are structured – to include a special combination of words and pictures in a certain sequence – increases students’ ability to remember information.”

The key word in the section above is “remember”. The purpose of a user guide is not necessarily to get the reader to remember, but to solve their problem. We want them back working as quickly as possible. Indeed, one of the key principles of Minimalism is “Support reading to do, study, and locate”.

Having said that, there are some interesting findings in the study:

“There are good theoretical reasons why comics might be better at imparting information to students. A lot of which has to do with what the influential cognitive psychologist, Allan Paivio, called “dual-coding theory”. This is the idea that we deal better with material which is presented in both a verbal and a visual manner.”

This means good layout and using graphics will help the readers of user guides.

Certainly for learning materials, comics can be very useful. Indeed, we’ve created a number ourselves.

DITA graphic novel - page 4

What has been your experience of using this medium?

Which type of platform is best for developer documentation?

At the Write The Docs event in London last night, Gergely Imreh presented Resin.io’s approach to customer-driven docs – documentation as self service support. Resin.io is a software company that provides Linux containers to the Internet of Things. It sees itself as a support-driven organisation, and so documentation is very important to them.

The discussions at the end of the talk were around which type of platform is best for developer documentation.

Resin.io uses an in-house system, based on Markdown and a flat-file publishing tool. They build pages from “partials” (snippets of re-usable chunks of information) to create “parametric information”. Pages can be built to match different criteria. For example, using Resin.io on a Raspberry Pi and Node.js. It provides an authoring environment that is easy for developers to use; it doesn’t require a database-driven CMS; and the content can be treated in a similar way to the code. The challenge with this type of system is getting it to scale. The “intelligence” of the system is through storing content in folders and using scripts within pages. As the grows, they are finding it harder to manage.

Gergely said he’d like see if a wiki-based system would work better. Content would be easier to edit, as pages would be more self-contained.

Kristof van Tomme suggested using a database-driven CMS. Pages would be built “on the fly”, by the CMS. In this situation, the “intelligence” of the system is through metadata wrapped around each topic and the database software that’s managing the content. The downside is it can mean there might be challenges in moving it to another platform at some stage in the future. You also have to manage the database and protect the CMS  from potential hacking.

Another suggestion was to use a semantic language to write the content. This could be AsciiDoc or DITA. In this situation, the “intelligence” is placed in the topics and with the writers: they “markup” sentences or paragraphs for each applicable parameter, such as audience and computer. These can be published as flat files or be managed by a database. This approach is scalable and tools-independent, but it requires much more work by the writers.

What’s best depends partly on your view of the problem. Is it a information design problem, a software problem, or a data management problem? There are pros and cons to each approach.

Is documentation a dirty word?

Daryl Colquhoun has written an article in tcWorld about the international standard ISO/IEC/IEEE 26512. He explained the standard is going to be revised and renamed: from “Systems and software engineering – Requirements for managers of user documentation” to “Systems and software engineering – Requirements for managers of information for users”.

The reason for this, he states, is because, in many parts of the world, the term “documentation” is associated with a printed manual only. The neutral term “information for users” refers to all types of content: Online help, audio, video, and Augmented Reality.

The problem with “information” is it can mean many things. Information for users could mean the weather forecast. We may well need to move away from the word documentation, but I’m not sure we’ve yet come up with a suitable alternative.