Testimonial – Depth in task-based documentation and structured authoring

Jason is a very experienced writer, with depth in task-based documentation and structured authoring. He is responsible, diligent, conscientious, and extremely easy to work with. I enjoyed working on his team very much and would welcome the chance to work with him again.

Jason was an important member of our team during a series of demanding and complicated releases of documentation related to regulatory changes to automobile insurance in BC. In the initial project, Product Reform, Jason joined the team responsible for converting reviewed Word documents into ICBC’s complicated DITA/XML toolset. To do this correctly (which Jason did) required mastery of information mapping and ICBC’s template structure.

For our second project, far less business preparation had been done, and the project itself suffered from a lack of business requirements and product definition. Jason took the bull by the horns and with intensive effort, managed to extract enough information from the SMEs to accomplish a successful release of a viable topic set.

Both projects required that “old” source co-exist with “go-live” source. Jason met the single-sourcing requirement using conditional profiles in DITA/XML.

—Lindsay Burrell, Procedures Analyst/Senior Technical Writer, ICBC

Testimonial – You did a fantastic job

You did a fantastic job communicating what the policy is, and distinguishing between “the program” and “facilities”.  It’s not exactly straightforward, but you totally nailed it.

—Kate, Senior Legal Counsel, ICBC

 

 

 

 

What’s your purpose?

What's your purpose?

What’s your purpose?

– or –

What’s the difference between a purpose and an objective?

Sometimes these terms seem synonymous, and often the term purpose is used solely to mean both, but the distinction between them in a document or training plan is key. The purpose is about the document and the objective is about the audience. In other words, “purpose” is what the document sets out to teach and “objective” is what the reader will be able to do as a result of that teaching.

Purpose

Example:

“The purpose of this guide is to describe how to complete a customer claim.”

I once saw a purpose statement at the front of a guide that stated, “The purpose of this guide is to be a user manual.” The circular reasoning is obvious, and it’s easy to see how feature-focused this kind of planning is. The purpose is the story the document is telling; or put another way, it’s the point of this guide.

Objective

Example:

“As a result of reading this guide, the reader will be able to complete
a customer claim accurately to company standards.”

Writing an objective in technical writing is a thornier issue and unless you’re writing training materials, it’s something quite foreign. The reason for this is simply that the objective describes something about the consumer of the information. Often, technical writers are removed from their readers. Technical writers don’t have to stand up in front of a room of readers, but trainers do, so instructional designers (those who write training materials) are more familiar with writing objectives.

In a technical document, I’m one for a blended approach and stating both, even if it means that the objective is buried in a purpose statement.

Purpose + Objective = Purpose

The result is something like this:

“The purpose of this guide is to enable readers to complete
a customer claim accurately to company standards.”

Big whoop—I know—it’s not all that different, but by taking in both the document and its reader, the purpose statement becomes much more meaningful (it’s not filler at the beginning of a guide), and the reader can go back to the beginning and assess if that objective was fulfilled (or not).

Testimonial – easily navigable, with understandable language and an accessible layout

I recently had the pleasure to work with Jason on a project for a new unit that I created. We had another writer work on a manual for my group, but the final product was far from what we needed.

I had a very brief conversation with Jason and he knew right away how to put together my document so that it was easily navigable, with understandable language and an accessible layout.

I learned a lot working with him and was so impressed with how quickly he was able to fix my document, which was almost 90 pages, but also how professionally he worked with me. The end product was better than I could have imagined and much more than I could have done myself. My team continues to use this document on a daily basis.

I highly recommend Jason for any writing project and look forward to the opportunity to work with him again.

—Erika Webster, Manager, Claims Business Support Unit, ICBC

Testimonial – I appreciate all you’ve done to contribute to our success.

Thanks for all your hard work converting topics from Word to Oxygen Jason. Everything published successfully for release 1.1 and I appreciate all you’ve done to contribute to our success.

—Brody Darough-Hardekopf, Senior Business Advisor, ICBC

Insurance Corporation of British Columbia (ICBC)

Role: Procedures Analyst (2018–2021)

Need: To comply with new government-mandated changes to automobile insurance, ICBC needs to revise all of its policy and procedural material. Projects included Rate Affordability Action Plan (RAAP), Modernization of Passenger-Directed Transportation (MPDT – otherwise known as Car Sharing/Ride Hailing), Material Damage (new Collision and Glass Repair programs).

Activities:

Working with business policy analysts and subject matter experts (auto insurance, healthcare, legal) to ensure readiness for province-wide rollout to ICBC’s internal departments and over 900 independent insurance brokers.

Tools used:

  • Darwin Information Typing Architecture (DITA)
  • Oxygen Authoring – XML editor
  • Information Mapping methodology
  • SharePoint
  • Jira
  • Confluence
  • Microsoft Office

Deliverables

  • hundreds of Oxygen Authoring reference, policy, procedure, and process topics
  • Conversation guides
  • many SharePoint adjuster strategy topics
  • Job aids
  • and more

Read testimonials about this position…

Testimonial — a proven IT consultant

Jason is a proven IT consultant and has been a pleasure to work with over the last few months.

When we were partnering to find his next position, Jason was always very committed. He was extremely easy to work with, was always open to making strategic changes to his resume, and most importantly, was always available to talk.

Thank you Jason!

—Robert Peterson, Account Manager

British Columbia Institute of Technology

Role: Technical Writing Instructor/Instructional Designer (2007–present)

Need: BCIT’s Department of Communications relies on instructors with industry expertise and still active in the field, so it was my 15 years of experience as a technical writer that brought me into their technical writing courses. In addition, while there I also attained the Provincial Instructional Design Diploma in Adult Education designation to ensure my teaching ability is the best possible.

Activities:

Classroom experience as core instructor for the Technical Writing Certification Program.

  • Employing learning objectives and ADDIE model to develop courseware.
  • Analysing learner needs, designing lesson plans, developing learning assessments and evaluation tools according to criteria and rubrics.
  • Implementing blended learning (instructor-led training (ILT) and computer-based training (CBT)), and evaluating effectiveness of learning against learning objectives and
    criteria.

Courses taught: Technical Writing Style, Technical Editing and Grammar, Writing for the Web, Business Communications.

Tools used:

  • Learning Hub (online learning management system)
  • Moodle
  • WordPress
  • Microsoft Office (Word, Excel, PowerPoint…)
  • Wiki
  • Adobe Acrobat

Read testimonials about this position…

WorkSafeBC

Role: Adult Education Consultant (2009) and Technical Writer (2018)

Need: WorkSafeBC (the Workers’ Compensation Board of British Columbia) needed to modernize the way it processed its claims. As an agency mandated to reduce workplace injury and illness, the new system needed to allow WorkSafeBC employees with the ability to use create and follow the progress of claims from admission to release (including all communications regarding workers, employers, and health care providers).

Solution: Working out of the Richmond, BC Head Office, I was brought in (2009) to write training manuals for the enormous roll-out of the system. Training modules included procedures for processing worker injuries, long-term disability, healthcare, wage loss, employee/employer entitlements, and more.

I coordinated with subject matter experts and ran procedures within the CMS (Claims Management System) system. The resulting manuals were used for a province-wide software roll-out.

In 2018 after nearly ten years, I returned to update technical and training materials for the new upgrade. To do this, I re-ran procedures (from 2009) and revised them according to changes in the new version of CMS. To ensure consistency across more than 800 documents, I also developed a style guide.

Tools used:

  • Claims Management System (an in-house managed IBM/Cúram Social Program Management enterprise module-based platform)
  • Microsoft Office (Word, Excel…)
  • TechSmith Snaggit (a screen capture and screen recorder tool to create and edit images and screen captures)
  • SharePoint (a Microsoft enterprise file-management tool)
  • Adobe Acrobat

Read testimonials about this position…

5 Questions Every Technical Writer Needs to Ask

One of the best skills a technical writer can bring to a company is the ability to ask good questions. When a technical writer shows up at your firm, he should be inquisitive and eager to learn about your content. Starting with the same kit of questions a journalist uses (what, who, why, where, when, how) the technical writer works with subject matter experts to ferret out the information the end user needs.

1. What is it?

Content…

Despite claims to the contrary, not knowing the particulars about a thing can put a technical writer at a distinct advantage. Why? It’s about empathy—about 75% of the time, technical writers are writing for people who share their initial ignorance, so they ask the best questions.

Subject matter experts, by contrast, may suffer knowledge blindness, a form of ennui brought on by over-exposure to the content. Experts have been so exposed to the difficulties of the subject matter, they can hardly remember how hard it was for them to learn it. As a result, assumptions are made, steps are skipped, and conclusions are drawn that seem premature to the reader.

A good technical writer exposes these oversights and writes with the fresh perspective of the reader who is new to the content.

Questions to ask:

  • What is it?
  • What is it used for?
  • What problem does it solve?

2. Who is it for?

Know Your Audience

Technical documents fail not so much because of poor content but because of poor audience assessment. As you can imagine, a software guide that patiently explains what a computer is to an audience of programmers is going to miss the mark—by a long shot! It’s about finding the Goldilocks zone of information—not too basic, not too complex, just right.

I took a PHP programming course in which the instructor got up one morning and launched into 45-minute lesson on how to use “regex”. I couldn’t follow him at all until my thirst for context finally overcame my patience and I blurted out “Where would you use regex?” To which he replied, “Everywhere?” That was clearly no help to me, so I opted for the reductio ad absurdum argument and said “Like on salad?”

This was likely the instructor’s first glimmer that perhaps I was in the wrong class, and this also coincided with him assuming a more condescending tone with me until the end of the term. He was otherwise a good instructor but made the blunder of forgetting that his audience was more novice (in my case, infinitely more) than he.

Armed with a good working knowledge of the audience for technical content, the writer can provide that needed context. Sometimes, it’s good to risk stating the obvious (that is, provide context even when it’s not necessary) as it provides reassurance or confirmation to all readers.

Part and parcel of knowing your audience is making informed choices about what sort of writing style you should use. If your audience is less educated, for example, prefer a simple direct writing style; whereas, if your audience comes from an academic environment, write in a more formal manner.

Some governmental organizations can tolerate a large amount of passive voice and nominalization (turning verbs into nouns), which other readers would find confusing or even condescending. Which brings me to tone (the other side of style). Tone is your attitude to the reader (or the subject matter). Whether collegial or more reserved, the tone for a document is developed from asking the right sorts of questions about the audience.

Questions to ask:

  • Who is the primary audience for this document?
  • Are there any secondary audiences?
  • What is education level of your audience?

3. Why does your audience need to know?

Purpose

Where context allows a reader to know the relevance of the content to something already known, purpose allows the reader to know what will be possible as a result of learning this new information.

Going in, very often, the reader has expectations of the document or the subject matter. The reader may already know things about the content or even have prejudices about it. If the writer can anticipate and address these expectations up front, the reader’s job becomes much easier.

Knowing this information may also help the writer tailor what might motivate the reader as well as address any resistance to the subject matter. For example, an in-house technical manual for a workplace automation tool may benefit with a disclaimer that this new innovation is not a prelude to the unemployment line for its readers.

Questions to ask:

  • Why should your readers care to know this information?
  • What expectations do the readers have for this document?
  • As a result of reading your document what will readers be able to do?

4. When do they need to know?

When…

Technical content sometimes has a shelf life that goes beyond ensuring it’s up to date. Sometimes, the information is only relevant to the reader at certain point and then not again. Once when I was working on a set of technical specifications, I found myself in a room with two subject matter expects both arguing about the specifications for the product. How could they be arguing? Aren’t specifications objective?

Once the air cleared, I realized it was not a matter of what we needed to say but where the document was positioned in the Sales funnel (a Marketing term). We were at the beginning, so the prospective buyer only needed to know if our product complied with their equipment standards. Later on (and further down the Sales funnel), the reader would need a different set of specifications that explained in more detail the requirements for installation.

I always provide connecting introductions to sections so that the reader knows if a particular section applies (or not). If a section is dependent on what came before, I mention that. Remember, readers don’t necessarily read technical documents in a linear fashion so it’s helpful to recap with connecting text. Also, readers appreciate knowing if a section doesn’t apply so they can skip it and move on.

Questions to ask:

  • At what part in the process/workflow does this apply?
  • What conditions apply?
  • What exceptions occur?

5. What’s the Structure?

Organization

Technical documents are not like novels—nobody curls up by the fire with their lapdog and a snifter of brandy to read their favourite technical manual cover to cover. No. Technical documents are only read when there’s a need. As a result, they’re highly structured to allow the reader to jump about as needed.

Creating the structure for a document is called outlining. The outlining stage of writing ensures the document is laid out in a logical and functional way. An outline usually appears as a document skeleton—just a structure, no details. Once approved, the writer fills in the skeleton with paragraph text. Think of a table of contents that precedes a nonfiction book: Major headings of equal value interspersed with sub headings containing subordinate content.

There’s a design element to structure too. Although readers tend to jump and skip around until they find the specific piece of information they need, technical documents are still written in a narrative (or chronological), so good structure (reinforced with heading styles) leads the reader’s eyes to your intended point of focus.

Questions to ask:

  • What’s the logical flow of the information?
  • What are the major components?
  • Where do sub components fit?

Do you have any questions about your documentation needs? Let’s talk.