The most excellent technical writer

As a Technical Author, one question an interviewer asks is what makes a good Technical Author? Based on my 23 years’ experience here is my take on what makes either a poor, a good or an excellent technical writer.

Poor technical writers edit the content and leave it at that. There are no questions, no curiosity even when a set of instructions do not read correctly. In which case, if that is you start looking for a new job.

Good technical writers :

  • Logically set out the steps starting at A and avoid no detailed Work Instructions leading to Step Z.
  • Methodically test the steps
  • ensure the content is easy to read and understood by reviewers
  • They know their ABCs

Excellent technical writers go a step further – we:

  • ask the question of why – who – what – when – where and how
  • analyse the problem the user is experiencing  
  • ask how the documentation will solve the problem
  • anticipate the issues users could encounter and the questions they will ask when they follow the material.
  • Build relationships with teams across the floor
  • Use humour and diplomacy to get what we want
  • Pretend we are a user reading the document for the first time
  • include links to related topics to keep the user briefed

All of the above takes time, effort, and creative thinking but as excellence is a byword we never feel the pain.

By covering the above points, the documentation will impact positively on the business. Excellent documentation increases user adoption, reduces the impact on your Support services, and aids your staff should a problem occur that could damage the company and its reputation.

Project Management and Doucmentation

The quality of project management has a direct impact on technical documentation, a fact project managers overlook . This article looks at the areas where the relationship between project management and technical documentation intersect. 

Put a plan around a project or a project around a plan

Technical documentation will suffer if the project is floundering without a project plan. A document project without a plan is always at risk of failure. There is a tendency by those with no documentation experience to change the goalposts and and add to the project because in many cases they did not listen to the experience and advice of their technical Writer. 

While documentation cannot compensate for the lack of a plan, it can help to revive a troubled project. This method of catching up through documentation will extend timelines, but will serve the project better by mitigating risks and strengthening the overall product through documentation analysis.

Frustrated

An experienced technical writers can certainly find their frustration peaking when the project timeline isn’t workable, or the Project Manager fails to listen to advice. THis happens when:

  • working with staff members who have no experience working with documentation and assume its an easy straightforward task
  • unworkable deadlines that sacrifice documentation quality and lead to frustration among internal parties

It is worth bearing in mind the following: 

  • when scheduling technical documentation tap into the TAs knowledge to help plan the timeline for documentation.
  • Writing or migrating content is not an instantaneous process; a failure to work with the writers could led to counter productive problems. 
  • If the timeline is genuinely tight, develop a list of documentation priorities in order for users to adopt the product.

A typical breakdown for a technical writing project includes:

  • Research time to learn the project and other elements, such as the underlying technology and related issues required for the documentation effort.
  • Dedicated time for writing.
  • Dedicated time for editing. copy editing and editing for style, clarity, and other issues.
  • Dedicated time to review the technical accuracy of the documentation. Never assume that a document is correct. Always create review time for accuracy by SMEs.

Allow sufficient ramp-up time

Technical writers need sufficient ramp-up time to become versed in the product. While ramp-up time is relative depending on the writer, a project manager can support the writer:

  • Provide ready access to necessary hardware and software so the technical writer doesn’t have to waste time waiting on equipment required for documentation projects.
  • Provide the necessary system access, usernames, and passwords.

Allow technical writers ramp-up time is more than a learning curve; it’s having the resources in place so they can perform their jobs with minimal downtime, which is billable when they are on-site waiting for corporate bureaucracies to deliver the resources they need.

Review the reviewers

While technical writers must have a stake in the technical accuracy of the documentation they produce, there is often a need for technical reviewers to review the documentation. Take into account this review time  in the overall project schedule, including:

  • Scheduled time for technical staff, project managers, and other reviewers to go over the documentation.
  • Time for the technical writers to add the revisions to the documentation.

Can project managers and technical writers get along?

The documentation component of a project requires input from technical writers to help ensure quality technical documentation. A working collaboration between project managers and technical writers can help organisations reap the benefits of better design (because it’s documented), and better customer support through documentation. A self-sufficient customer who doesn’t call customer support is like money in the bank for your company.

Welcome to the Gutenberg Editor

Of Mountains & Printing Presses

The goal of this new editor is to make adding rich content to WordPress simple and enjoyable. This whole post is composed of pieces of content—somewhat similar to LEGO bricks—that you can move around and interact with. Move your cursor around and you’ll notice the different blocks light up with outlines and arrows. Press the arrows to reposition blocks quickly, without fearing about losing things in the process of copying and pasting.

What you are reading now is a text block the most basic block of all. The text block has its own controls to be moved freely around the post…

… like this one, which is right-aligned.

Headings are separate blocks as well, which helps with the outline and organisation of your content.

A Picture is Worth a Thousand Words

Handling images and media with the utmost care is a primary focus of the new editor. Hopefully, you’ll find aspects of adding captions or going full-width with your pictures much easier and robust than before.

Beautiful landscape
If your theme supports it, you’ll see the “wide” button on the image toolbar. Give it a try.

Try selecting and removing or editing the caption, now you don’t have to be careful about selecting the image or other text by mistake and ruining the presentation.

The Inserter Tool

Imagine everything that WordPress can do is available to you quickly and in the same place on the interface. No need to figure out HTML tags, classes, or remember complicated shortcode syntax. That’s the spirit behind the inserter—the (+) button you’ll see around the editor—which allows you to browse all available content blocks and add them into your post. Plugins and themes are able to register their own, opening up all sort of possibilities for rich editing and publishing.

Go give it a try, you may discover things WordPress can already add into your posts that you didn’t know about. Here’s a short list of what you can currently find there:

  • Text & Headings
  • Images & Videos
  • Galleries
  • Embeds, like YouTube, Tweets, or other WordPress posts.
  • Layout blocks, like Buttons, Hero Images, Separators, etc.
  • And Lists like this one of course 🙂

Visual Editing

A huge benefit of blocks is that you can edit them in place and manipulate your content directly. Instead of having fields for editing things like the source of a quote, or the text of a button, you can directly change the content. Try editing the following quote:

The editor will endeavour to create a new page and post building experience that makes writing rich posts effortless, and has “blocks” to make it easy what today might take shortcodes, custom HTML, or “mystery meat” embed discovery.

Matt Mullenweg, 2017

The information corresponding to the source of the quote is a separate text field, similar to captions under images, so the structure of the quote is protected even if you select, modify, or remove the source. It’s always easy to add it back.

Blocks can be anything you need. For instance, you may want to add a subdued quote as part of the composition of your text, or you may prefer to display a giant stylised one. All of these options are available in the inserter.

You can change the number of columns in your galleries by dragging a slider in the block inspector in the sidebar.

Media Rich

If you combine the new wide and full-wide alignments with galleries, you can create a very media-rich layout, very quickly:

Accessibility is important — don’t forget image alt attribute

Sure, the full-wide image can be pretty big. But sometimes the image is worth it.

The above is a gallery with just two images. It’s an easier way to create visually appealing layouts, without having to deal with floats. You can also easily convert the gallery back to individual images again, by using the block switcher.

Any block can opt into these alignments. The embed block has them also, and is responsive out of the box:

You can build any block you like, static or dynamic, decorative or plain. Here’s a pullquote block:

Code is Poetry

The WordPress community

If you want to learn more about how to build additional blocks, or if you are interested in helping with the project, head over to the GitHub repository.


Thanks for testing Gutenberg!

👋

Technical Writing | General Data Protection Regulations

GDPR

On the 25th May 2018, the new General Data Protection Regulations (GDPR) came into force.

Companies outside the EU

If your Company actively trades within the EU and stores, processes or shares EU citizens’ data, then GDPR does apply to you.

Compliance and documentation

One of the primary rules is that under GDPR Process activities MUST be documented.

Companies are required to maintain a set of Policy, Process and Plan (PPP) documentation to ensure you have evidence to support your claims should the ICO investigate any complaint or breach of data.

Note that the Information Commissioners Office (ICO) could demand to see the written documents

What do you need to consider?

As a technical writer, with experience writing compliance documentation, what can I tell you?

If you are still struggling to start

My Blogs are clear, writing one document, when there is a substantial list to be completed from scratch to sign off is a lengthy process. Even if your department has documents that can be reused, it will still take a long time. Compliance projects are manually intensive and documenting GDPR will need dedicated resources.

My experience could be necessary to help you write and manage those documents. The sooner you contact me, the sooner we can start the road to compliance.

  • Create a standard template with – Statement, In Scope, Version Control, Change History, Distribution Lists, Roles and Responsibilities
  • All PPPs must adhere to GDPR – include in the document ‘The purpose of the document’, ‘The Scope’ and add a list of the GDPR compliances relevant to the PPP you are writing and explain the WHY the company are complying along with the HOW the company will comply.
  • The documentation must be relevant to your business. Generic documentation outlining a PPP will NOT suffice
  • Complete the documentation – do not start and leave a document incomplete then sign off; an incomplete document could fail a Compliance Audit
  • Maintain the detail – do not half explain a process or policy
  • Structure the documentation to avoid duplicating information over several documents
  • That the documentation may need to be ISO 27001 compliant

Does Your GDPR Project need documentationClick To Tweet