Technical Documentation

IXIASOFT CCMS

2019-07-30T21:05:00.001+05:30

IXIASOFT CCMS

Story of an API writer

2016-01-23T11:12:00.000+05:30

An API writer is a part of API ecosystem and creates API guides for better understanding of an API. To get into this role, you must be ready with your safety gears to play with live wires – APIs.

For a user guide or online help, a technical writer needs to be familiar with its application and the tools to generate the help. While an API writer burns their hand to know in-and-out functionality of an API, jumps into the codes, reads through API specifications and user stories (in case of agile project), and analyses the traces of an API. API guide comes in a raw format – just like a tomato without any garnishing, whereas online help comes with much glamour – tomato in salad.
Mostly, developers are main audience of API guides. They refer it to know about the API specifications, where they mostly look for the base path of APIs and resource URIs. In addition, users can also view the list of methods that are applicable to a request and their payload values, which is available in a code snippet. The parameters and error code descriptions are also some extra information available in the API guide.
You need to update your guides as of when an API story pass through the scrum board and deployed on pre-production and production servers. In between, get your document reviewed from SMEs and publish it for your users.
You need to assist in onboarding of developers in developer portal. Where they become part of API ecosystem and interact with APIs using their own Apps.
So, your role is not only restricted to writing API guide, but also read through the black-and-white codes and troubleshoot developer queries.
Let me clarify on the type of developers available in the API ecosystem. First, one who create APIs and second who access API resources. API guides are mainly catered for the latter.
Don’t get upset if you get only Microsoft Word for writing API guides. Gear up with Swagger – a way to describe APIs through JSON and YAML schemas.
Let’s have a reality check!
Architect provides the API specifications in the API ecosystem. These specifications cover most of the API knowledge areas in bits and pieces. The presentation and language are not much of importance when presented in a Swagger tool. Therefore, need for an API writer is minimum or not needed to create API guides.
However, you can buy food for yourself by creating demand in the API ecosystem – presenting clear and concise information about the APIs, having some hands on coding, and creating YAML files for the APIs.

Audio recording through TechSmith Camtasia

2015-05-03T01:00:00.000+05:30

In this procedure, you will able to avoid an error when selecting the audio recording option. This will also solve the frustrating issue of unexpected shutdown of Camtasia.

On the Tools tab, click Camtasia Recorder.
On the View tab, click Audio Toolbar.
Note: You can turn on and off using the Audio Toolbar option.
Click the Record Audio icon, to record real-time audio as you record the video.
Now you can click the Record icon.
Camtasia starts recording with audio.

Is Help without TOC becoming the new trendsetter…

2015-04-15T18:24:00.000+05:30

Whenever we get some help creation task, first we probably think about TOC. Managers mostly like a structure that helps them to create estimation and the placeholder for the Help content. TOC becomes the best framework to complete their milestone to complete the documentation task, how the information is chunked, and avoids duplication.

Whereas online users want their Help to be easily searched and solve their problem in a single topic. The online help is not relevant when it’s presented in a TOC structure. Sometime an application has context sensitive help. Users usually don’t navigate the help hierarchically, they just search their problem through keyword and land to that particular topic. For example, LinkedIn Help.

The FAQs comes to great rescue to a particular problem and the list of popular solutions can be displayed through analytics. Help can be available in blended formats, where TOC is a part of the solutions. For example, refer Amazon Help.

Therefore, TOC is now becoming a myth. It’s now the need of the users to get the relevant information instantly.

Technical writers wearing multiple hats

2014-12-12T18:56:00.002+05:30

Technical writers should have the blended knowledge of writing and tools. While tools do not only mean software used for documentation, it also includes the application software about which writers need to work around. Manager need to decide whom to involve based on technology of a project. Content update related project would prefer a content enthusiasts, whereas a technical resource for technology centric project.

The phrase is common among us that it hard to train people on language than on language. In technical writing, a person has come across so many jargons and tools on which need to learn as part of the project requirement. In a big organization, we have a team comprising of writers, editors, and managers. Among writers, also someone is expert in tools, who can provide assistance on tools and obviously an editor who pinpoints on the clarity of the document.

For technical writers it is always good to work in team where intra-communication elevates the quality and productivity of documentation. However, some of the budget of company and/or project or does not permit to maintain a team on writers. Then the picture comes where a writer need to wear multiple hats for documentation related task. In such situations, the person needs to take the responsibility of managing their own task.

Steps-by-step procedure to submit IT Return

2014-07-12T20:39:00.000+05:30

July month is the time to file you IT return. Income Tax Department has come up with an easy way to file IT return.
Step 1: Log in to the Income Tax Department site. (https://incometaxindiaefiling.gov.in/).
Note:

For registration, PAN card is mandatory, and this number will be your user ID.
Keep your Form 16 handy, that is provided by your company.

Step 2:
a. In the Quick Link section, click Quick e-File ITR.
b. Provide the IT returns detail as illustrated in Figure 1.
Note: If you have income from any other source other than interest (such as, shares, property deals, and other), which attracts tax under different clauses; select correct ITR form.
Figure 1. Prepare and Submit Online

Step 3:
a. In the Personal Information tab, provide your personal details.
b. Click the Save Draft icon.

Step 4:
a. In the Income Details tab, provide your income details as illustrated in Figure 2.
b. Click the Save Draft icon.
Figure 2: Income Details

Note: In the Tax Details tab, you can view the TDS deducted from your salary. This value is auto-generated from your PAN details. If there is any tax payable amount, pay your tax through online banking and provide the details in the Sch IT section.
Step 5:
a. In the Taxes Paid And Verification tab, verify tax details and provide your bank information.

Pay Tax – If D17=0, no tax is payable for you.
Refund – If D18=0, Money will be reimbursed to you. The refund amount is credited to your bank account through ECS.

b. To submit your IT return to Income Tax Department, click Submit.
The Income Tax Department site flashes the message about successful e-filing on the web page. The acknowledgment form — ITR—Verification (ITR-V) will be sent to your email ID.
Note: You can submit IT return when D17=0.
Figure 3: Taxes Paid And Verification

Note: If you donated any amount to relief fund, for example Prime Minister's National Relief Fund, provide the details in the 80G tab.
Step 6:
a.Take a printout of the form ITR-V that you receive in your email ID or download from the Income Tax Department site.
b. Sign the form ITR-V preferably in blue ink.
c. Send the form ITR-V only by ordinary or Speed post to the Income-Tax Department-CPC , Post Bag No-1 , Electronic City Post Office, Bangalore - 560 100, Karnataka, within 120 days of filing your return online.

Deleting unused images in RoboHelp

2014-05-05T23:18:00.003+05:30

You can view the list of unused image files in the RoboHelp project from: Tools>Reports>Unused Files. However, you cannot delete those files from the RoboHelp project. You can delete the file names from the Windows Explorer, which is a tedious work and prone to error. It becomes more challenging when the size of your project is big and files got filled up during several updates.

RoboHelp support java script to automate the task in the project. Don’t worry if you are not expert in java script. You can download the imagecleanup.jsx that is freely available at: https://www.wvanweelden.eu/product/image-cleanup

Open the RoboHelp project for which you want to delete unused images.
To open the Script Explorer pod, click View>Pods>Script Explorer.
The Script Explorer pod opens.

Image: Add caption

In the Script Explorer pod, click the Import Script files icon.The Select script files to import dialog box opens.

Image: Select Script files to import
Select the imagecleanup.jsx file and click Open. The script is added in RoboHelp.
To delete the unused images from RoboHelp, select the script and click the Run Selected script File icon.

Image: Choose action
In the Choose action dialog box, click Remove unused images. Note: Take backup of unused files as these images are deleted permanently from the location.
Image: Script Alert
In the Script Alert dialog box, click Yes.
The Output View pod displays a list of all the images that are removed.

Technical Writers vs Instructional Designers

2013-08-19T19:54:00.000+05:30

The objective of a technical writer is to help the users in using the product. When a user is struck in understanding a feature or task, they consults the document as a reference. While an instructional designer make the user learn. The learner needs to go through the complete instructional design deliverable. If we talk about WBTs or CBTs, each and every activity of learner is tracked. The learner uses the instructional design deliverable as a textbook and not as a reference guide.
To conclude, technical writers write documents for potential users while instructional designers for potential learners.

Scenario-based learning

2013-05-12T02:15:00.000+05:30

Scenario based learning is the becoming popular to showcase a feature of an application. Scenarios are based around actions, where you need to create a story and the characters who will perform the task in the application.

If you tell your story effectively and create good characters, your learners become invested in that character's story, regardless of whether they're rooting for their success or their downfall. Once you have your training plan outlined and sequenced with your lessons, you are ready to begin. Introduce the character and then present her/him with a problem that they (and the learner) cannot overcome. Develop the story so that it steps the learner on a journey through the learning objectives, getting the knowledge and skill along the way to meet the challenges presented at the outset of each learning objective.

Creative writing courses will help immensely with storytelling as well as scenario based learning, but you may also think about technical writing for complex procedures.

To learn more about scenario-based learning, view the demonstration to buy books from Amazon.com on Youtube.

Lucidchart quick start guide

2013-03-11T11:59:00.001+05:30

Introduction

Lucidchart is an HTML5-based diagramming tool to create flowcharts, wireframes, UML diagrams, mind maps, and more. You can open this tool on a Google chrome browser and work with the team members in real time.

Installing Lucidchart

To install and configure Lucidchart with Google Drive:

Go to https://chrome.google.com.
The Chrome Web Store page appears.
In the Search Apps text box, type Lucidchart and press Enter. In the Apps tab, the result page displays the Lucidchart: Diagramming app.
Click Install.
A confirmation message asks whether you want to install Lucidchart on Chrome.
Note: Before installing Lucidchart, sign in with your Google account.
In the confirmation box, click Add. The
Lucidchart dialog box appears.
To install the Lucidchart on Chrome, click LAUNCH APP.
The Lucidchart website opens in a new tab.
To integrate Lucidchart with your Google Drive, click Integrate with Google Drive.
To enable Lucidchart with Gmail account, enter your user name and password. This integrates Lucidchart with your Google Drive.
The Lucidchart registration page appears.
You can register with appropriate Lucidchart usage plan, or try it for 14 days. To register, enter your Google credentials.
The Google Drive Integration page appears.
Select the appropriate option to synchronize Lucidchart with Google Dive, and click Save Changes.

You receive a confirmation e-mail to Gmail account. Now you can access Lucidchart from the Google Drive.

Using Lucidchart from Google Drive

Instead of opening Lucidchart website, you can directly create, save, and share Lucidchart diagrams using the Google Drive. The Lucidchart diagrams that you create are listed in the Google Drive, so you can easily open, edit, and store it.
After installing Lucidchart on Google Drive, you can:

Draw diagrams by dragging the objects on the canvas.
Collaborate the diagrams with the users of same domain or send invitations through Google contacts.
Store the diagrams on Google Drive and backup on the computer.

Installing Google Drive

You can access files from the computer using Google Drive over the internet.
To install Google Drive:

Open the Google Dive link (http://drive.google.com) on the browser.
The Google Drive sign in page appears.
Enter your Google account credential and sign in.
The Drive page appears.
To sync files from your computer to My Drive, click Download Google Drive for PC.
The Download Google Drive for Windows dialog box appears.
Click Accept and Install.
The Google Drive installation starts.
Complete the instructions of the installation package.
Start Google Dive on your computer.

You can copy the files on the Google Drive and synchronize with My Drive.

Do you like to read a user guide or view a video tutorial?

2013-02-12T13:36:00.002+05:30

People prefer instant help, sometime they don’t like to read the content to find the answer of their queries. It is helpful if someone shows you the steps to solve the problem, rather than navigating the user guide and troubleshoot the problem. People sometime prefer a video tutorial to view the how-to-do task.

Nowadays we get everything on mobile, prefer a video or online help for a product. For software products, printed document will soon be past. The internet and mobile has reduced the distance between the user and the vendor.
The product simulations and demonstrations can attract the attention of people. A technical writer can create video tutorial by using the Captivate and Articulate, these e-learning tools can also create course and quiz for the learners.

The sales personnel prefer a product demonstration for the clients and seminars. These demonstrations give a better walk through the product in a nut shell, instead of running the product. The beta version of the product might not be ready on time or create run-time error.

People can grasp the features of a product by watching the tutorial at their own time. Watching a video is always fun than reading a document.

What managers want?

2012-06-20T12:07:00.001+05:30

Managers want to see the ability to manage the documentation project, starting from initiating the task and meeting the users’ need. It is appreciated, if a tech. writer can provide some value added services, like suggesting on the UI texts, workflow diagrams, visual aids, and features. Developers want to see that you're familiar and invested. They want to work with resourceful and proactive tech writers. Your specific questions will reflect how much you're actually working with the technology. Never the less some time follow ups are required to get confirmation of your queries and assumptions.

Captivate: control flash animation

2012-01-25T14:46:00.000+05:30

When there is an audio flash file in your Captivate slide and the user click next, the sound of the animation might not stop and it keep playing in the background of the next slides. This issue does not happen when you preview the project, but for the published file. The problem can be solved as per the the following three cases:

Case 1: In Cp 5.5, under the AUDIO section of the button properties, click to select the Stop Slide Audio When Clicked check box. Note that this feature doesn’t work, if the sound is embedded in the FLA file.

Case 2: If sound is embedded within the FLA file and you can edit the flash file, bring the embedded sound at the top level in the timeline of the slide.

Case 3: If sound is embedded within the FLA file and you cannot edit the flash file, create an advance action. In the advanced action, you can define two actions: hide the flash and go to next slide. The hide action will stop the sound of the flash file.

RoboHelp: Breadcrumbs

2011-11-28T00:23:00.003+05:30

When I created breadcrumbs through the WebHelp Navigation – WebHelp dialog box, then breadcrumbs were created on top of the HTML header. In other case, when breadcrumbs were created through master page, breadcrumbs were created below the header.
However, I wanted the breadcrumbs above the header. What would be the answer???

Ohhh.. I think Im close to my answer. I removed the header, instead of that I used a simple text in the master page, which I used it as a header for the HTML files. Then I inserted the breadcrumbs. That was simple....

SWF for Android Phones

2011-08-23T17:36:00.008+05:30

I successfully played a SWF file locally (by copying it in the SD memory) on a Dell Streak through this link:

file://sdcard/[filename].swf

However, my friend could not play on Xoom (Android 3.0 Honeycomb) through the same link. Then I figured out that there was also a same issue with Acer Iconia Tab A500, which also runs on Android 3.0 Honeycomb.

Then a flash developer came to my help. He converted the SWF file into the APK format that could be played on Xoom.

Text animation

2011-07-03T00:21:00.001+05:30

In the Captivate (4.0), I wanted that after the Text Animation object is over (i.e., not in loop) then the text should display for rest of the slide.

TIP: For the Text Animation object, take the Effect as Typing Text and kept its Delay for: Rest of the slide. The text remains on the screen after the animation is over. The real time typing cannot be copied to other slide, and then you can replace it this Text Animation.

Cross-reference with Soft-return

2011-02-23T10:32:00.001+05:30

The MS Word soft return would mean line break due to word wrapping. In numbered list, if soft return is used, then the whole text is seen in the cross-reference pop-up window. So, it’s better to use separate style for the description of the numbered list.

I can't stop playing games with software.....

2011-01-10T15:44:00.008+05:30

Tools and software makes me crazy!!! I do really have soft corner for the software and their usage...
I always tried (& keep trying) to become a techno-wizard.

Now, IT profession has be forefront with the latest technology trends and software updates. One can enhance their skill by practicing on a Tool.

Once Einstein quoted that if a person spend 10000 hour of on one subject then he/she becomes specialist on it.

However, as in the case of Technical Writers most of us have to wear many hats of tools and software, and give their best in the crunch of deadlines. Even a person working in a single tool for many years, how many has explored all the available features. The fact is that, we keep doing the same task if there is no requirement or scope is within the boundary.

Sometime, mastering the similar tools simultaneously is difficult.

· Word/FrameMaker

· RoboHelp/MadCap/Authorit

It is always challenging to work on multiple platform and technology. I put my hat off to those who do multi-tasking. In IT industry, we go ahead with a slogan as “Just to it”.

Multi-Language

2010-12-12T20:55:00.006+05:30

Multilingual people in IT help to build the harmony and brotherhood among the people, where most states of the India are divided on the basis language. IT is a huge resource pull of technical peoples of different region, religion, caste, language, and gender are present. Hindi is India’s official language and English as second official language, outsourced jobs are boarded in India because of skilled English speaking peoples. In addition, because of multilingual peoples are working in a single place, they are sometime forced to talk in English.

In India, many universities and institutes provide foreign language trainings. There are many doctorates in French, Spanish, and German languages. Now, these foreign language skills are used in IT companies and India too is able to attract jobs from European countries.

Curve text in Microsoft Word 2010

2010-12-07T19:13:00.004+05:30

In the lower versions of Microsoft Office 2010, the curve text feature is not available through WordArt.

Trick: Save the Microsoft Word 2010 document in 97-2003 format. The old feature of WordArt is enabled. Now, you can use the curve line feature.

It is observed that you cannot play the same tricks in Microsoft PowerPoint 2010.

Trick: Copy-paste the curve text from the word document into the PowerPoint 2010 slide. Hurrah!!!

Bloom’s Taxonomy in Technical Writing

2010-10-24T19:25:00.008+05:30

The application of Bloom’s Taxonomy consistis of presentation, design, and assessment strategy. It can be used in e-learning, web-based training, or user manual. An application level objective requires simulations and step-by-step description. While, higher level learning requires case studies and role plays.

Six Levels of Cognitive Domain:

Knowledge: The information should be well-defined and explained to the user satisfaction. Describe the product background and features.
Keywords: defines, describes, identifies, knows, labels, lists, matches, names, outlines, recalls, recognizes, reproduces, selects, and states.
Comprehension: Understanding of the application should be summarized. Describe the interface and behavior of the product.
Keywords: comprehends, converts, defends, distinguishes, estimates, explains, extends, generalizes, gives, infers, interprets, paraphrases, predicts, rewrites, summarizes, and translates.
Application: Put the statement into action and relate the application with the document. Describe the product in step-by-step process.
Keywords: applies, changes, computes, constructs, demonstrates, discovers, manipulates, modifies, operates, predicts, prepares, produces, relates, shows, solves, and uses.
Analyze: Scrutinize the information and verify with latest data. Provide relevant screenshots and references.
Keywords: analyzes, breaks down, compares, contrasts, diagrams, deconstructs, differentiates, discriminates, distinguishes, identifies, illustrates, infers, outlines, relates, selects, and separates.
Synthesis: Create and predict the data. Describe how one action affects the product usage.
Keywords: categorizes, combines, compiles, composes, creates, devises, designs, explains, generates, modifies, organizes, plans, rearranges, reconstructs, relates, reorganizes, revises, rewrites, summarizes, tells, and writes.
Evaluation: Interpret and justify the information. Proofread and verify it by SME.
Keywords: appraises, compares, concludes, contrasts, criticizes, critiques, defends, describes, discriminates, evaluates, explains, interprets, justifies, relates, summarizes, and supports.

Microsoft Word numbered list

2010-08-27T16:50:00.006+05:30

I am quite happy with MS Word 2010 for many reasons. Among them, I found numbered list is pretty robust than the earlier version of word. It does not break now and user need not to play tricks to bring the numbering in shape. However, I found an interesting fact of numbering format.
If the existing number list has bold text and the same list text are copied into other part of the document. After restarting the numbered list, the source text changes from bold text changes to normal text.
TRICK: Press Ctrl+z, the text returns to the previous format.

Copy and paste

2010-06-26T17:26:00.000+05:30

In IT industry, copy (CTRL+C) and paste (CTRL+V) action is the major action. Someone might have truly said that if "C" and "V" buttons are removed from the computer keyboard, then most of our work would come into standstill.
Once I faced an acute problem with the copy-paste action in MS Publisher, in fact there was nothing wrong with Publisher. I was not able to copy text from other application like, notepad. Within the Publisher, text and objects could be copied pasted. Then, I looked in the clipboard; there I found everything was copied into the clipboard, but not in the actual insertion point.
The easy solution I found as most of the computer user that I closed Publisher and again opened it. Ahh.. now my copy-paste action works fine. This is not the solution of what I faced, but it might be one of

Snagit window capture

2010-05-07T09:58:00.008+05:30

Snagit 9.1.2 window profile captures the application window. However, Java application by-passes the native operating system and shows the child window through the “swing” technology. This makes job of Snagit difficult to capture the child window or a dialog box individually.
I posted this problem to the Snagit support team. Let see, if Snagit's next version comes up with a solution.

Simple work

2010-03-02T13:23:00.006+05:30

The task you could do easily is said to be “simple work.” If you are asked to fill some color using a paint editor, you would do it quickly. Now, if you are asked to edit an image in the Photoshop editor, then you need some knowledge on it. First you would find many tools available, most of their usage you don’t know. You try to look for some help or training, otherwise lot of time is spend in searching and trying your hand in all of them to get your required result. At the end you would exhaust yourself; you would get fear with the work and try to avoid the task.

The scenario would change, if you would get some overview of the product and know the purpose of the tools. This is the case of every user irrespective of their domain knowledge. Basic knowledge is required to work with product. So, here comes the “Help” that could be a tutorial, user guide, demonstration, and so on.

I think of myself, when I first get into the product and run for help, asking my teammates for assistance. I go through the knowledge transfer session, and made a list of questions to ask the SMEs. I still find myself in a comfortable zone surrounded by peoples who could at least answer my queries. After all I am getting paid to know about my company product and give the best out of my effort.

The user who stats from the scratch, have no knowledge of the product, would get difficulty in doing their work. In the market, there are many vendors to provide the same product; however, the price is a different factor to convince the purchase. Therefore, in the trial version if the customer (user) is not handy with the product. They would never go ahead to purchase it.