Using Markdown to create a boilerplate document for reports and proposals

Following on from our post Cutting and pasting content into Word documents – Is there a better way?, we’ve been looking at how organisations could use Markdown to create reports and proposals more quickly and consistently.

The objective was to:

  • Create something simple for non-technical people to use.
  • Have a collection of re-usable chunks of content that could be embedded into the document (no more cutting and pasting). If a chunk needed to be changed, then the documents where it is embedded would reflect that change automatically.
  • Be able to generate the completed report as a .docx (Microsoft Word) file.
  • Separate the content from the “look and feel”.
  • Enable different people to work on different sections of the document simultaneously.
  • Store the content in an open format, so there was potential to use some of the content in other places (such as on a website).

Continue reading

Cherryleaf’s policies and procedures writing – Next course 24th November 2015

Cherryleaf’s first public policies and procedures writing course will be held on the 24th November 2015, at our training centre in central London (SW7).

Discover how to create clear and effective policies and procedures. Cherryleaf’s policies and procedures course teaches your staff how to write clear and effective policies and procedures, in a straightforward and efficient way. This course is for anyone involved in writing or editing policies and procedures.

Places are limited to a maximum of 10 delegates.


Creating palaces of almost forgotten things

Museum of almost forgotten things brochure

This weekend, we went to the Fabularium on London’s South Bank, where the programme highlighted The Museum of Almost Forgotten Things. It struck me that this concept could also be applied to technical communication. The impetus to write things down, to document policies and procedures and to write user documentation for software written in a Sprint, is often due to organisations worrying that important information might be soon forgotten. Technical Authors often capture and record almost forgotten things. They might, however, object to the word “museum”, because they are working with how things are today much more than how things were in the past. So perhaps “palace” could be an alternative word to use.

Ben Haggerty, the storyteller whom we saw perform, started by trying to discover who we, the audience, were. He quoted a west African saying that there are four types of people in the world:

Those that know and know that they know. These are called teachers, and should be respected.

Those that know, but don’t know that they know. These people are asleep.

Those that don’t know, and know they don’t know. These people are students.

Those that don’t know, but don’t know they don’t know. And there are 630 of them sitting in the House of Commons on the other side of the Thames.

It’s interesting to see how close this old African saying is to competency models used in training today: unconscious incompetence, conscious incompetence, conscious competence and unconscious competence.

Tips for writing in the business world

Writing in the business world can be difficult. We have to write Web pages, proposals, emails, policies and procedures and, perhaps, adverts. It can be hard to get going, and create something that’s clear and to the point. Here are some tips to help you get over these difficulties.

It’s not your fault

Let’s start by saying it’s not your fault if you find business writing difficult, because most of us are not taught how to do it at school. At school, we learn how to write stories and how to argue a case. That usually involves building to a big conclusion at the end.

In business, mostly we have to write to:

  • persuade
  • instruct, or
  • inform.

Those are different forms of writing.

Continue reading

Why business writing is so difficult

“Everyone is taught to write at school, so surely everyone can write in business?”

Although the quotation above would seem to make sense, the reality is that many people find it hard to write in a business context. They struggle to write clearly, and it can take them ages to produce a piece of content.

It’s not their fault. What we’re taught at school is how to write narratives, that is stories or articles. We’re also taught to argue a case – to use rhetoric to build to a conclusion. We’re taught writing to persuade and writing to entertain.

In the world of business, we often need different forms of writing. We’re often writing to inform or writing to instruct.

In these situations, people want to know what they should and shouldn’t be doing, and get on with their jobs. They want the important information at the beginning, rather than the end. They want to scan and hunt for the information relevant to them, rather than always having to read everything from beginning to end.

Many people haven’t been taught how to write to inform or to instruct, and that’s why many people find business writing so difficult.

The sad case of GDS and the tax manuals

The UK’s Government Digital Service has been doing great work in putting users’ needs before the needs of government, so it was a shock to see the revised tax manuals the GDS and HMRC published recently.

In the GDS blog post, First HMRC manual on GOV.UK – give us your feedback, Till Worth explained:

“HMRC has built a new publishing system which makes it easier for its tax experts to update and maintain the content of the manuals. Tax agents, accountants and specialists need to be able to see the tax manuals exactly how HMRC publishes them internally, so the GDS team knew we couldn’t touch the content. We did create a new design for the manuals to make them more user-friendly and bring them in line with GDS design principles.”

From what I can see, there’s been two changes:

  1. New look and feel
  2. Changes to the navigation and search

Continue reading

New case study – Creating an operations manual for a medical service provider

You’ll find a new case study on the Cherryleaf website, regarding a project we carried out for Affidea.

Affidea Group BV is a company that offers premium diagnostic imaging, cancer detection and cancer treatment services. It focuses on delivering prompt, thorough diagnoses and high quality treatments by working only with state-of-the-art technology and experienced medical professionals.

AffideaAffidea operates a network of Diagnostic and Cancer Treatment Centres in 14 countries across Europe. The company employs over 3,000 professionals, of which more than 750 are medical doctors.

Affidea required us to produce a so called “Blue Book” of company operations. Some of the material for the Blue Book already existed and had been documented; other material had not been documented. The existing material had been written by non-native English speakers and/or non technical authors, because of this there was a lack of consistency to the existing documentation. The information required for the new material was largely not documented anywhere and subject matter experts (SMEs) were based throughout Europe.

The project involved re-designing/writing existing content, interviewing SMEs in order to get the information required for new content, putting together new content and finally assembling all the information into the Blue Book.

For the full case study, see:

Your policy and procedures manual as software

Jared Spool tweeted this morning:

HyperCard was a hypertext program that came with Apple Macintosh in the 1980s. It allowed you to create “stacks” of online cards, which organsiations used to create some of the first online guides. It also contained a scripting language called HyperTalk that a non-programmer could easily learn. This meant HyperCard could do more than just display content: it could be used to create books, games (such as Myst), develop oil-spill models, and even dial the telephone.

Continue reading