Artificial Intelligence & Writing

The new and evolving technologies like AI, machine learning are not only making organisations smarter, but also making consumers more aware and smarter. I am doing quite a bit of research on Artificial Intelligence and looking forward to my project on chatbots. Here is a presentation on “Impact of AI on Technical Writing” that I presented at HPE in June, 2017.

Advertisements

DITA with FrameMaker

[Source: Gyanesh Talwar: https://thecontentgym.wordpress.com/2014/02/06/video-tutorial-getting-started-with-dita-using-framemaker-11/]

To use DITA to create content, you essentially need to know how to:

  1. Create tasks, concepts, and references. (Covered in Video 1 and 2)
  2. Compile these topics into a ditamap (Covered in Video 3)
  3. Publish the ditamap to create PDF and other deliverables. (Covered in Video 3)

And this is what we are going to cover here.

This series of 3 tutorials will walk you through creating your first DITA deliverable using FrameMaker 11:

For best learning:

  1. Perform the steps on FrameMaker as you see the video playlist: Download free trial.
  2. Use speakers/headphones  – videos have audio instructions (2/3 videos have audio and the third one’s audio is coming soon)
  3. View the video multiple times and read up on terms being spoken about in the video

The three videos in the playlist:

  • Video 1. Creating a DITA Task using FrameMaker 11 – Tasks in DITA are created for procedural or instructional information. The structure of a DITA task guides you to create your task files according to a standard with ease.
  • Video 2. Create a DITA Concept using FrameMaker 11 – Conceptual information that is paraphrased is put in the Concept topic types. For example, a topic with three paragraphs with introductory information about a software application is perfect for a Concept topic.
  • Video 3. Compile Tasks, Concepts, and other files into a Ditamap and generate a PDF deliverable.

 

No Love Lost for an SME

I have started to live with it and so has my customers. As more and more technical documentation is done in multiple locations scattered across geographies, it is inevitable that we learn to adapt. In the context of Blue Dots Consultancy Services, I see a signboard that says, “adapt or lose out”.
In my experience, the main issues besides from the documentation writing standards that may differ, there is a an Subject Matter Expert (SME)experience or the domain experts, who are located at various locations and things could become difficult while interacting with them in various time zones.

Image

  • The best way to source documentation is getting a face-to-face interview with an SME. With the time zone differences and locations, documentation timeline may change. SMEs may have their own line of work and getting their time to contribute may be tough.  
  • Language can be an issue at times. With all due respects, English is the second language of a many of nations and it becomes extremly difficult when you have to explain each and every question repeatedly.  A good idea would be to create a  video recording of the SME demonstrating a new feature. As more technical authors read specs and come out their documentation, the videos can be useful.
  • Sometimes, owning to time constraint, you expect the SME to provide the details quickly.  But time may be a factor stopping you from collating the inputs. Consider working with a shared review tool like Acrobat Pro X or an Author-it Reviewer. It allows you the opportunity to have real-time inputs coming straight to your documentation set.

About Blue Dots Consultancy Services:-Pioneered in the year 2014 and based out of Bengaluru (India), Blue Dots Consultancy Services is one of the agile and just-in-time Consulting startups that creates innovative solutions for solving critical business problems faced by the Content management and Documentation industry. Coupled with exceptional customer centric mindset and the hunger to create success for the ecosystem, Blue Dots believes that it can create disruption in the industry and create its niche. Hardly a few months into operations, Blue Dots has already delivered a good number of successful projects and is in discussion with a few large customers. You can read the company services here.

The Last-Minute Documentation Changes

It has happened with me a couple of times, and I am sure you must have come across it too. Yes, you are correct, I am referring to  the last-minute changes to a documentation project. Besides the angst  it also sometimes creates chaos in documentation.

Typically, the last-minute documentation changes comes from the:

  • user experience design team,
  • software development team,
  • and software testing team.

Image

You are in midst of a deadline. Release is happening today. Certainly, out of nowhere, there are a few changes that have arrived. What could you possibly do? what should be your approach? I have tried to come up with couple of strategies that have been tried and tested:

  • Prepare to have your content in metadata so that customers can find it in their knowledge base system and you can push out the content with the last-minute changes rapidly. Think more in the lines of dynamic help rather than context-sensitive help.
  • Set up a responsible system so that customers/users/clients can access the documentation in their mobile devices.
  • Prepare to reuse content and set up certain business rules that takes care of your documentation. Reusable strategies can be employed at regular places. Think of considering embedded topics by the help of which you can do a last-minute update of your source content and the changes gets reflected in all the other container topics.
  • Loop yourself in the projects. You should be in the chain of emails aware of any last-minute changes to the software or network application. Be better prepared lest it comes.
  • Don’t cringe : It is better to get on with the task because an annoying face will never make things right. Get into the task, document the changes, and then ensure that there is a definite process followed the next times certain situations like these arise.

About Blue Dots Consultancy Services:-Pioneered in the year 2014 and based out of Bengaluru (India), Blue Dots Consultancy Services is one of the agile and just-in-time Consulting startups that creates innovative solutions for solving critical business problems faced by the Content management and Documentation industry. Coupled with exceptional customer centric mindset and the hunger to create success for the ecosystem, Blue Dots believes that it can create disruption in the industry and create its niche. Hardly a few months into operations, Blue Dots has already delivered a good number of successful projects and is in discussion with a few large customers. You can read the company services here.

How to sell your ideas?

Everytime I hear someone say “I have a great idea”, I am both curious about the idea as well as how the idea will be transformed into something intangible. Maybe it is incorrect on my part to qualify every idea in the tangible and intangible brackets, but when you have a decision to make to provide a quality experience it matters. Over the years I have come across ideas and wondered why they never failed to take off. In this post, I’ll mention approaches to make an idea work especially if you are working in an user experience or technical writing team.

Image

1. Embrace change: Nobody likes to beat and come out of their comfortable zone. As a result learning new technologies could be a matter of interest but different in matters of execution. I distinctly remember couple of years earlier with the privatizaton of Telecom in India, a lot of Senior Telecom Officers recruited during the pre-computer era were put down to trainings and assignments. I could understand the agony that they went through to get back to classrooms, but when I meet couple of them now all of them say nice things that how technology has made their jobs easier and wish it were there earlier. Learning to embrace change is important here. If you get disturbed by the work that you have to do to execute an idea, then you can never make an idea work.

2. Develop a strategy: Having an idea needs a working strategy. The ultimate objective is selling your idea. Let us take an example of a DITA project. You could have a scenario that your company has piles of documentation with a lot of components getting repeated across multiple deliverables. Your idea is to implement a DITA based structured authoring process withing your organization. What can be your strategy? You can base your strategy where the tech pubs team can plan to release documents for a product in DITA as a pilot. You will employ all the necessary resuable strategies (conref, topicref, mapref and all) in all your DITA topics. Then once the company has given a go ahead to it, you can release the documents release by release in DITA formats according to their bandwidth and capability.

3. Back yourself:  Be pragmatic and repeatable. And at the same time the ideas should talk about numbers. And it should be easy to measure and report and easy to gather consistently and frequently.

4. Always be open to questions: The management while are supportive of the ideas need to rationlize their decision making. I found myself in situations while introducing usability testing to an organization the department quizzed me on several rounds. Largely the questions revolved around cost and tools and also if one is able to deliver. Failing to realize that you’ll be up against certain tough questions and competitions can lead one to certain catastrope.

It is great to listen and appreciate when someone comes up with an idea. But it is equally important to ensure that ideas are replicated with stamps of rationality and data.

About Blue Dots Consultancy Services:-Pioneered in the year 2014 and based out of Bengaluru (India), Blue Dots Consultancy Services is one of the agile and just-in-time Consulting startups that creates innovative solutions for solving critical business problems faced by the Content management and Documentation industry. Coupled with exceptional customer centric mindset and the hunger to create success for the ecosystem, Blue Dots believes that it can create disruption in the industry and create its niche. Hardly a few months into operations, Blue Dots has already delivered a good number of successful projects and is in discussion with a few large customers. You can read the company services here.

Requirement gathering is a key

I can’t possibly wear a mask and tell my students and trainees that “all’s well”. I run a business and even if it means that I should ignore certain things to get more revenue for business my instincts forbade me. One of the things that I try to acknowledge and showcase them is “tools are important but your writing skills are even more important in technical writing.” Some of them do not like when I am blunt. A few do not even call back to register for the technical writing program even when they had initially signed up for it. But I feel it is important that as technical writers we should ensure that writing addresses and becomes the the backbone of a good structured program.

Image

When we conduct a program on technical writing, I focus and spent a great deal of time on the basics. Generally, I ask my trainees to write a paragraph or two on a technical topic. This initial exercises without their knowledge provides me insights into their research and writing skills. I always believed in the philosophy that technical writing is spending 60 percent in requirement gathering and the rest 40 percent in putting the information in a document. The other key aspect in documentation is requirement gathering.

  • Understand the product or application to be developed
  • Gain an understanding of the domain or subject matter
  • Understand client requirements for documentation
  • Study legacy documentation and writing style guides used by the client
  • Provide content consulting or evangelism
  • Propose documentation deliverable and tools to be used
  • Prepare effort estimate
  • Propose team size and composition

Requirement gathering is a key:

  • If the requirements are incorrectly, inaccurately or incompletely specified there is little chance the solution will be what is needed.
  • Requirements are the basis on which potential solutions are assessed.
  • Requirements identify what is needed. They are not the solution, rather they provide definition of what the solution needs to address.

About Blue Dots Consultancy Services:-Pioneered in the year 2014 and based out of Bengaluru (India), Blue Dots Consultancy Services is one of the agile and just-in-time Consulting startups that creates innovative solutions for solving critical business problems faced by the Content management and Documentation industry. Coupled with exceptional customer centric mindset and the hunger to create success for the eco system, Blue Dots believes that it can create disruption in the industry and create its niche. Hardly a few months into operations, Blue Dots has already delivered a good number of successful projects and is in discussion with a few large customers. You can read the company services here.