Category Archives: Uncategorized

Lessons from Remote Learning

Lockdowns during Covid would have turned technical writers with children in to very busy people. Recently, I’ve been reflecting on how home-schooling my son became like another occupation when schools were not open. I picked up many things from being exposed to my child’s e-Learning platform and also teaching in general.

The Seesaw e-Learning Platform

The school teachers used the Seesaw Learning platform to deliver content to the children. Seesaw made me think of the software tools that I use for technical authoring. Teachers can record video, create exercises, link to presentations, offer feedback, and enable students to interact with the content – all in a very simple package. The great thing about the content was that I could use it on a PC or on an iPad. This was important because, at the time, we were very constrained with computing resources at home. The laptops were used for work, which only left us with the iPad. It wasn’t easy as we were using version 3 of the iPad and contending with an unreliable internet connection.

Video-Driven Content

The integrated features of Seesaw made me think of the limitations of the current tools we often use in the workplace as technical writers. In Seesaw, video is a key feature of the platform. In technical writing, it’s different as video tools are often separate from those we use for writing. When creating a video, we would often use a separate tool solely for that purpose, e.g., Camtasia. And then once we have video, there is the issue of where to include in the video in the documentation. Should the video be added alongside reference content or overview content? As videos are often an afterthought due to their complexity, it is not often easy just to slow a video in to the documentation. Adding a video is often an afterthought. With Seesaw, content is from the start “video-driven”. The daily activities include a video to start and the students are guided in to various activities for their learning.

Blending in of External Module Content

Seesaw is a package that lets the teach add different learning modules in addition to what they teach. My son’s learning on Seesaw was split between instruction from his teachers and from external presentations that came with the learning module. This enabled the teacher to present the basics while the presentations would provide more detail. Documentation systems very rarely link well with Powerpoint or Keynote presentations that are presented by “someone else”. There may be instances where the internal audience feel that the real nuggets of information are never presented. This is partly because we write purely on the features in development to meet tight sprint deadlines, and rarely create integrated content that may fall outside the timelines of Agile release cycles.

Interface Allowing Instant Feedback

My son was able to get prompt feedback whenever he submitted his work. Quick feedback is often difficult to receive in technical documentation. Part of the reason lies in the available interface widgets or our intention to use feedback forms to provide data that is tied to business and team objectives. For example, feedback forms on many documentation sites and portals ask the reader to give a score.

While this can work in some situations, there is the benefit of a simple design of a text box accompanied by a Like button. Several years ago, I worked at a company that used Confluence for both internal and external documentation. Using a very simple design that allowed the audience to make comments and/or put a Like on the page proved effective.

Writers should never have to wait a significant period for the response, particular if the content needs approval for the stakeholders or is to be used to help build a community.

Presenting Concepts Visually

Teaching mathematics to my son, who is in Year 1 in a UK primary school, was a great experience for me in communicating concepts. Teaching numerical concepts made me think how technical documentation can be better improved through visual communication.

The mathematics modules included number blocks and various concepts, e.g., the part whole model. Describing such concepts to my son became fun.

Visual communication when done well is very effective in technical documentation. Some readers learn better with text while others pick up knowledge quicker with images.

Realising the Power of e-Learning

Helping my son through remote learning made me realise the power of online content during lockdown. Given that it was an “emergency” situation, the teachers did a remarkable job in creating effective e-learning content based on the limited available resources. Technical documentation can be boosted from e-learning even though they are not the same.

As technical authors, we need to re-evaluate the documentation systems we already have to be able to reach out to our audiences. We need to constantly ask ourselves if the documentation fulfils the needs of the target audiences, and the impact of the pandemic in online content. While primary school students will continue to use the content, our audiences can go elsewhere if they are unhappy!

Technical Writing in the Near Future

At an interview, a product manager asked me “what it is the future of technical writing?” I found it difficult to quickly answer this rather open-ended question. Though unable to recall how I answered it, I recently thought about the question again.

Without a doubt, game-changing developments in the software field will change technical writing in the future. But based on today’s technologies what will we be able to see fairly soon?

Text Will Become an Option

Where using products becomes intuitive, text may be optional. Thus an interface may no longer need explaining. Text is also misunderstood in different instances. In turn, this can affect the quality of translations.

However, text will continue to pervade in technologies that needs explaining, especially those that are emerging.

Steps as Infographics

Infographics will probably become more common when conveying procedural information. During the Covid pandemic, I’ve seen infographics warning people about protecting themselves; which has made me think of our reliance on infographics to explain procedures. Here is an example infographic from the World Health Organisation.

The presentation of steps has evolved over time. In the late 90s, procedures consisted of many steps and sub-steps. In recent years, step have become less rigid, allowing scope for creativity. Thus numbers are often presented as attractive icons alongside images.

Animation

Animation may replace the use of screenshots and static diagrams. Animation is starting to appear in documentation in SVG format (see Ox.org – a platform for Ethereum). This is no surprise given that we are consuming more animation content than ever before.

For example, Cocomelon – Nursery Rhymes was ranked in 2021 by Tube Filter as the 2nd most viewed YouTube channel with over 761 million weekly views. There has also been a huge increase in animation-based explainer content on YouTube. Personally, I found animations on YouTube very useful when learning new technical concepts.

Through a set of animation elements, it is easy to turn an SVG image to animation. Javascript libraries are readily available to animate SVG files (see 8 Javascript Libraries to Animate SVG). But expect more animation options to exist in the future, and we may no longer need the assistance of web designers.

Video Video and More Video…

We often produce video to describe interfaces or concepts. Video is likely to become more common in documentation as video editing technologies become easier to use. For example, recording screen shares in Microsoft Teams is simple, thus allowing quicker creation of content to describe user interfaces. Just like a film offers another dimension over a book, a video is an exciting alternative to text-based user guides (see Exploring the World of Video Guides).

In the near future, video collections are likely to be closely integrated with help center content. Some companies maintain a library of videos on YouTube, e.g., Salesforce. However, the text-based content of a help center/documentation site and a video channel is still largely separate.

User Assistance Text

Text will become even more integrated with the user experience of a product, where we could view content before clicking on a link or downloading a user guide page. User assistance text will instantly give you answers to questions of what the feature is and how and why you would use it. In this example, users can open a mobile app and find out how to use it for editing.

How the text appears depends largely on the design of the app. Text may appear directly in the UI, as pop-up text, or within “empty screens”.

In more ways than one, companies could both gain business and save money with user assistance text:

  • Customers could try out a product without the support of a sales representative, allowing them to get started quicker.
  • Customers would be less likely to call support.
  • The production costs of the documentation would be integrated with those for front end development.

In Chris Stokel-Walker’s article on Increment, Sara Feldman from MindTouch mentions that “Documentation becomes relevant far sooner in a customer’s journey than it used to. In fact, it becomes relevant at the very, very beginning of a customer’s journey, whether that’s automated or with a human.”

Authoring software will become better for creating and managing user assistance text. Managing user assistance text is already possible to an extent with some packages. MadCap Flare allows the integration of micro content, which is summary information that appears when searching within a help centre.

Chatbots

Technical authors will be able to further integrate their content with chatbots. Many technical authoring principles, such as topic-based writing and structured content, can be applied to chatbot design. Chatbot design may even become part of technical authoring, while engineers will take care of development.

Transcribed Content

With video becoming more common, the alternative “text form” user guide could even be a transcription of the video. Presently, there are various apps that generate transcriptions when a user pays a certain amount per minute, or pays via flat monthly fees (see this Techrepublic article). Good quality and feature rich transcriptions are likely to be available in the future.

Audio User Guides

There is a use case for audio user guides catering to visually impaired users. Some public places currently use NFC (Near-Field Communication) for connecting to audio guides. The Informaze blog mentions about using this technology within churches in Milan. RSF International provide technologies for audio guides in tourist locations.

Moreover, learning through podcasts has become increasingly popular. The PlayerFM site lets you acquire knowledge of all sorts of things. Audio guides may help users that have a distinct preference for audio learning, especially conceptual information that does not require interacting with a user interface.

More Legacy Content in HTML or PDF Form

Lastly, we will see more legacy content available in print or web form that that never previously existed. Think of vital documents that have been stored in filing cabinets for years. Publication technologies will enable legacy content to exist as PDF manual and/or HTML pages, albeit with access control. For example, consider a user guide with information on nuclear waste content that only needs to be available for specific users, but has to be accurate. While newer content will exist in the latest forms of video and maybe even animation, such timeless content may not be superceded.

Happy Writers and Unhappy Customers

This could be a common situation when customers are consuming your documentation. You’ve produced good work in researching the product, creating a blueprint, applying the writing style, and getting comments from developers. Your JIRA tasks met sprint objectives and were done in time.

Why Could Customers be Unhappy?

Unhappy customers may not be because the content is poorly written or is accurate. It may be because they have had problems using the documentation.

But Your Documentation is on a Website!

Your documentation is available to all from a website. You’ve picked a documentation tool that has effective templates, is easy-to-use, and fits nicely with the technical requirements of the software (e.g. it is a jamstack solution that uses static site generators). No matter how well-implemented or attractive the documentation appears in its design, it still doesn’t help the needs of the consumer.

Customers Still Call Support

When customers have no time, they would rather call support than read through the content. Even if the content is rich and informative, it may not help in certain situations. They may try to call support even though the documentation is there. Moreover, your company may have dedicated support channels, and they know who to call.

Understanding the Customer Journey

Whether or not a customer reads the documentation, their journey starts when they arrive at your site. They should be able to make a decision from the home page as where to go next. Normally, this is through a search or via the navigation menus.

Short Form vs Long Form Content

Short-form content gives the customer a brief synopsis of the product or functionality, allowing them to understand the product and make decisions on what to read next.

Long form content is information in more detail, covering procedures, reference material, and further concepts.

Both forms of content go together. Users may stop after reading the short form content. That’s great if the short form text provides all the information they need. Or, they could venture further in to the long content.

Search

Many users explore the documentation from a search. Therefore, ensuring that the pages are findable from their keyword combinations is key. If your site is implemented in MadCap Flare, you can configure search by setting up various search tags. But if your documentation site links to a provider like Algolia, setting up search is almost automatic.

Navigation Menus

There are many ways to design navigation menus. While a left-hand menu bar is common, there are documentation sites with additional navigation menus in the main pages. This design exists in the Spotify help centre and the Akash Network. An over-crowded left-hand menu bar alone can make a site hard to navigate.

Organising the Pages into a Logical Order

Once customers know where to go, organising the pages in a logical order is essential for completing their journey. Depending on how they use your content, there may not be a complete right or wrong answer. For example, one helpdesk team informed me that typical customers would be less likely to read conceptual content before doing the steps. This differed from my own learnings of the product, and the initial feedback that I received.

Defining Quality

Lastly, improving the documentation to help customers should be part of a definition of quality. In her presentation at Write the Docs Prague in 2016, Riona McNamara from Google explains that quality in technical documentation can be defined as either Functional Quality and Structural Quality (see As Good As It Gets: Why Better Trumps Best). Structural Quality focuses on the immediately tangible areas that make documentation quality, e.g., the way it is written and laid out. Functional Quality, on the other hand, is whether the documentation achieves what is supposed to do.

In short, you could consider these two definitions in your plan to improve the documentation and make customers happy.

Learning the Basics of Git in Technical Writing

Today, Git is all the rage in the software world. It is a distributed version control system for tracking changes, and is widely used in today’s workflows where remote working is becoming the norm. Although mainly used by developers, many job descriptions for technical authors in the UK list knowledge of Git as a requirement.

I’ve found that using Git was quite tricky at first but was relatively straight-forward once I understood the concepts.  

Here are some aspects of Git that may help in your learning and use of this powerful version control system.

Git Provides a Unique Type of Document Management

I first learnt about the importance of document management in the context of files many years back. In a scenario where authors are working collaboratively, the golden rule is for you to update the file that is most up-to-date, and ensure that the other authors are updating from the same file. This was fairly easy to do if that single file was a 200 page word document. However, with Git you are not effectively managing files; you are managing “work” that can be shared across multiple files.

Git Responds to Specific Information you Provide

What Git does is determined by your instructions. Git can perform many powerful operations when given the correct commands. Thus, it is important to learn the key operations that Git can do. For example, Git add lets you stage a particular file. If you do not understand the concept of staging, then it can be difficult to perform tasks correctly.

When you use Git, you need to enter commands with the relevant flags. Thus, it is best suited for those who are good with the command line (I prefer Windows). But on a daily basis, you only need to use a few of the 170 commands that are part of Git.

Git Bases its Knowledge from Staging and Committing

When you understand how staging and commits work in Git, everything else seems to fall in to place.

At the heart of Git’s operation is the commit. A commit is a change to the Git database that Git knows about. That change could be to a single file or to multiple files that can take the form of an insertion, update, or a deletion of data. Your documentation can have new paragraphs, sections, or global CSS changes that are part of the same commit. You can set however many changes you want to commit. But for better tracking, you should minimise the number of changes within the commit.

Staging is the process that opens your work to a commit. If there is any change that you do not want to finalise, then it doesn’t have to be committed yet. But at least the change should be staged.

As I mentioned, Git is a service that responds to your instructions. Without you telling Git to stage a file, Git doesn’t know if that change exists. For example, if you have created a new file in Windows, Git has no idea that file exists before it is staged. And when you commit the file, Git knows that you have created a file of the specific name.

Renaming and Deleting a File

When you do a commit in Git, Git remembers the actions done on your “work”. It also remembers the name of the file associated with the commit. How Git responds to your “next action”, the rename, is determined by what it currently knows from the commit.

If a file is renamed, Git thinks that the file uses the old name. At this stage, according to Git, the file is “untracked” and “unstaged”. You will then need to stage and commit the name change for Git to know the new name. Similarly, if you have deleted a file, Git thinks that the file still exists if the change is not yet staged or committed.

The Man with Two Brains

Git, when installed on your computer, consists of a database that is a copy of everything in the remote Git location. Each repository is likened to a brain, and Git can be thought of as a person that has two brains. From the commits, Git knows the location of every file and changes within the local repository. However, Git also knows this information about the remote repository. Thus, Git lets you ensure that your local changes are in sync with the remote repository when you perform push and pull functions.

When you do a pull, Git copies the entire contents of the remote repository to the local repository. If any files are missing on your local computer, you may see an error. If any file contents differ from those in the remote repository, you may see merge conflicts.

Committing and Pushing Changes on a Regular Basis

You should commit and then push these changes to the remote location whenever you update your content. Both your local and remote repository need to end up with the same content. Thus, there should be the same number of commits in both repositories. You should not end up in a situation where your local repository has accumulated uncommitted changes.

You should also commit changes to your local repository to ensure it is up-to-date. The worse thing that can happen is pulling from a remote repository which results in your local content being overwritten.

Understanding Writing Restrictions

If updates to specific documents where you work can only be made by SMEs, you should ensure that none of these files contain your commits. This will prevent any unwarranted merge conflicts.

It is absolutely vital that you are informed of these restrictions in your workplace to prevent issues further down the line. If you want to make any changes to the content, these need to be made with the appropriate workflow outside of Git. For example, you may want to suggest changes over email.

Using Atlassian SourceTree

While Git is designed for the command line, SourceTree lets you conduct Git operations via the UI. There are many useful features in SourceTree including a visual map of the commit history of your database. The map also shows merges that took place on the remote repository.

Related Git Links and Book

Lastly, here are some useful links from:

Hackernoon

Atlassian

GitHub

Sarah Maddox

Tom Johnson

I can also recommend the book Git for Humans by David Demaree, which is available on Amazon.

Happy learning!

Why PDFs can be Better Than HTML

Last September, I spoke at Technical Communication UK about building HTML documentation from an infrastructure of PDFs as the company I worked at wanted to modernise their documentation. HTML delivers modern sleek documentation from help centre pages, Knowledge Base articles, to blogs. But PDFs still exist in many places — even within the sleek websites — and they are also useful in their own ways.

For over 20 years, PDFs have allowed the publication of long manuals of over 100 pages. The PDFs that I used to create were definitely lengthy, but were also tricky to generate and cumbersome to maintain. Above all, long PDFs are harder to read,

PDFs can Provide Short Targeted Information

As a reader of manuals, I enjoy reading PDFs that present shorter and more targeted information. PDFs let you view information on a software product without the distraction of other navigation information that exists on in HTML help topics. For instance, MadCap software have many PDF guides for brief and key topics. And you can find these PDFs from Google.

PDFs can be Presented for Business Purposes

Your documentation may be very important to your business. Like a contract, the documentation may even need to be printed and presented to an authority or client, and even signed off. In general, online documentation does not provide the same capability. While online solutions are becoming more popular globally in business, in many countries, presenting printed material is the norm. And PDFs may be an essential medium if your content is legally bound.

Appear the Same on All Devices

PDFs have the added benefit of appearing in the same way on a PC, mobile device, or tablet. As a technical author, you do not have to consider responsive design when producing PDFs, as this is taken care of by the site. However, for HTML pages, you may have to consider the device that your readers are using. This is particular true if your documentation is on a standard website that is viewable on a PC, or available as a mobile app.

Seamless Integrate Within a Website

The home of PDF is often within a website/help center itself, amongst the rest of the web pages that have built-in navigation. As long as the information is findable, then it doesn’t always matter whether or not the content is a webpage or a PDF file. Thanks to the sophistication of today’s web technology, PDFs can be stored seamlessly with your help pages.

Printed Documentation as Part of a Package

If your product comes in a physical package, you probably want to be able to pick up and use the manual. The manual is likely to be printed from a PDF file. If your product comes in attractive packaging, your printed manual is likely to have the same attractive design, e.g., a booklet. With the advancement of IoT, artificial intelligence/robotics, we see more and more gadgets with an accompanying manual. The web is just another medium for product documentation.

Which Format do You Choose?

If you can decide a format, it is worth considering all customer and business requirements. Although unsuited for long documentation, PDFs are definitely here to stay. And PDFs can even be used in tandem with HTML formats.