Sunday, September 23, 2012

Windows7-Nokia Lumia 800 - two taps too many and no help in sight

Note: Although the following looks like text, these are images (Blogger did not allow me to re-size images within blog posts). Click on each image to read.

Addendum:  Finally, "Help + How-To" worked! This is possibly WebHelp mobile output (that is htm pages for mobiles) and can be viewed in the default viewer (no need to launch a browser to view the topics). No ePub downloads are needed (such as PDF or Kindle for example). However, internet connection is needed and Help is not available offline. This is where the Mobile Phone's sync problems take its toll.

Note that the term "Tile" is used for Icons, "Start" for Home screen, and "Flick" to describe the touch screen slide gesture.

Wednesday, August 15, 2012

Parallelism when writing for Tablets

I was writing an install procedure for one of our software products (for tablets) and just thought I should share my thoughts on the style for referring to tablet names.
I compiled a list of tablets available in the market.

Usual name
Amazon Kindle
Barnes and Noble
Nook Color eBook
Samsung Galaxy Tab
Toshiba Excite
Toshiba Thrive
Dell Streak
K1 Ideapad
Lenovo Ideapad
Tablet S
Sony Tablet S
Motorola Xoom
Evo View
HTC Sprint
Google Nexus
Apple OS
Apple iPad
BlackBerry OS
BlackBerry Playbook
HP TouchPad
Slate PC
Windows 7 Home Premium
Samsung Series 7 Slate PC
Windows 7 HomePremium32 bit
Windows 7 Professional
HP Slate


The usual features users need are size, storage, Internet connectivity (WiFi), apps, etc. The tablets run on different processors and Operating System (OS). However, the OS seems to be the main category by which tablets are known.

The three most popular OS are: Apple OS, Android, and Windows.
The "devices" are known by different names. For example:
  • Apple's tablet is iPad
  • Blackberry's tablet is Playbook
  • Dell's tablet is Streak
Devices that run on Android (as many companies offer these tablets) are commonly known as Android tablets. Of course end users might know and buy Motorola Xoom or Samsung Galaxy tab with Android, etc.
Similarly for tablets that run on Windows, the usual reference is to Windows tablets.
So when writing a procedure (probably installation and configuration procedures) for a product that works on a specific tablet, the heading would be:
- My Product Procedure for iPad (not Apple iOS 5 - the OS for apple tablets!)
- My Product Procedure for Android tablets
- My Product Procedure for Windows tablets

Note that we call iPad - the device - Apple iPad. This is the deviation in style! We skip Google in the Android name and Microsoft in the Windows reference.
Strictly...if we write a procedure titled, My Product Procedure for Apple iPad, referring to the device name, then we should have My Product Procedure for Samsung Galaxy tab or My Product Procedure for Acer ICONIA! But that would be going overboard and into too much detail. What we actually mean is: "My Product Procedure for Tablets that run a) Apple OS b) Windows OS c) Android OS, and so on."
Therefore, I think it is best to keep it as My Product Procedure for Windows Tablets or My Product Procedure for Android Tablets. The plural form "tablets" is NEEDED to cover all tablets that run on Windows or Android. (I also read somewhere that tablets and tablet PCs mean the same.)
The only problem would be if at all a different company other than Apple suddenly offers their own tablets with Apple OS! Then we might need to change the heading for the My Product Procedure for iPad to "My Product Procedure for iPad tablets"! Or ask Apple to make their OS name popular :)

Monday, February 14, 2011

Unfriendly Error Message on Google Chrome Browser

I logged on to using Google Chrome and got the following error message when I tried to click on a link for making a transaction:
Diffie-Hellman is a cryptographic technique (cipher security method for authentication). This works like RSA algorithms and uses public-private keys to exchange information between two mediums securely. To describe rather vaguely, first, information that needs to be exchanged is encrypted and assigned two secret keys - public key and private key. This encrypted information can be decrypted only if you have both the keys. Someone might get hold of the public key as it is available publicly during transactions. However, this information is useless as the private key is required to decrypt the data. BOTH private keys are needed to exchange information. A simple example could be the several banking web sites that offer customers a device to generate their own private keys which the customer would use to log in to the banking website. The security methods vary and often keys are used in combination with passwords, tokens, or other authentication means.

Anyhow, the point of this post is not to delve into cryptographic keys. You can get information on cryptography and keys on the world wide web.

I want to talk about this particular error message.

Diffie-Hellman technique can be implemented in 3 different ways:

  1. Anonymous key exchange (Keys are exchanged without authentication and is a weak method)
  2. Fixed key exchange (here known keys are exchanged and is reasonable secure)
  3. Ephemeral Key exchange (here the keys are temporary and created during the transaction and is a strong method).
Ephemeral = Temporary
Ephemeral is a word often used in literature but avoided in technical and user documents. Although, it is used in the textual description as "ephemeral Diffie-Hellman public key", this error message should have been rephrased. Something like "Connection on this website is not secure."

Then the next sentence has the phrase "disastrous misconfiguration". This is really scary! Could have read as "This is a problem with the server on the website you tried to log into.

Next the marketing slant "Chrome won't use..."

Which user likes to see such unfriendly error messages? The same website however worked when I used Internet Explorer!

Friday, December 10, 2010

Madcap Flare - the unbind option in conditional tags

Madcap Flare, the Help authoring tool, allows you to "single-source" using conditional tags. You can show or hide paragraphs, images, glossaries, TOC entries, bookmarks, content files such as style sheets, page layouts, topics, and so on. I am not going to talk about the steps involved in producing multiple results from one source (for more information on conditional tags and how to display content selectively in outputs, see Madcap Flare's Web Help).

I just want to write about a Madcap Flare feature that I like - the unbind option in Conditional tags.

As Flare offers a bit of structured authoring, some similar style items are ordered (bound) together. At least this is the case with Lists, Drop-down text and Expandable texts. Flare does not restrict you if you insert a Heading 2 immediately after Heading 3 or such. However, within lists and drop down text Flare does not let you directly add a new style. If you press "Enter", after a bullet, you only get a bullet on the next line. So you need to copy a style and use the Paste before or Paste after option to insert a Heading 1 style between two bulleted items for example. Alternatively, you can use the unbind option to remove the style completely and make paragraphs after which you can apply the style you want.

Okay now back to conditional text and how the unbind option is useful here.

Let’s say you want to provide two outputs - Help topic for a. for new administrators who may need more information and b. administrators who know the product well. For the new administrators you want to provide a hyperlink to an installation procedure, whereas for the existing users you just need to display the text.

The text currently reads:

You want to display the same text without bullets and hyperlinks for existing users. To do that follow these steps:

1. Open a Flare topic and go to Projects > Conditions to define a conditional tag set.

2. Next create two tags in the tag set you have created - Existing and New.

3. Select the list or text or hyperlink or drop-down or image for which you want to apply conditions. Right-click and Select Conditions.
4. In the Condition Tags window, select Existing Admin Tag and in Exclude Action choose Unbind.

You have created a conditional tag set and created two tags. You have applied these to hyperlinks that you now want to apply to appear as text only to existing admins. Next you need to associate the conditional tags with a target. To do that

1. Go to Project Organizer > Targets.
2. Create two new targets - one for existing users and one for new users.

3. Double-click the target for existing users.
4. In the Target Editor, select a tag set and to exclude the applied tag from the output select Exclude.

5. Save your work. Build the outputs and view the results.

Note: In this case, the selected output will still be displayed without the hyperlinks as you have selected the Unbind option. So existing admins see the two hyperlinks as text. New users will see the links.

Similarly, you can unbind images from expand text, bulleted list, snippets, files, etc.

Thursday, December 9, 2010

Documentation in an Agile environment - observations from project

Although these are specific to the project I work in, there could be a few items common to others working in a similar setup.

Tuesday, December 7, 2010

Writing for applications accessed through mobile phones and touch-screen-enabled devices

As mobile phones and other handheld devices start offering exciting technologies and tools to users, the way information is accessed too varies. Mobiles are no more used for only calling - they are used for accessing email, playing games, sending text and multimedia messages, transacting on bank websites, shopping online, and social networking. Tablets such as the iPad from Apple, Galaxy from Samsung, Streak from Dell, Slate from HP, are trying to combine the best of the laptop and smartphone worlds while reading devices like the Kindle from Amazon offer a new reading experience.
Meanwhile, touch screens have become common on mobile phones and other devices.

 Technical writers are in for an interesting phase as writing for such users offers newer challenges. Some observations:
  • The devices are all small meant to be used anywhere. So any content has to be primarily for online purposes (no one will want to lug a printer on the bus :)) 
  • User attention spans are shorter
  • Smaller devices although convenient in terms of access are not great for doing "work"
  • Users find it difficult to read when the pages scroll too much or when there are too many pages to jump through 
  • Users will probably do other things - like attending a call in between tasks 
  • Users might want to share information and would look to post content to websites and friends
Therefore, if users need help or information, they will think of the user guide as a last option. The information in user help has to be crisp and to the point. This requires a lot of planning. The TOC should be for example very high level as smartphones are not great for navigation back and forth across screens. Procedures have to be real short. If the user requires more information, provide a link to that. But watch out - too many links make it tough to navigate. Avoid images as a rule.
Navigation gets complex as you need to deal with both touch and standard screens. Screens are smaller or larger and any content has to look fine both vertically and horizontally. The next advance would be double sided mobiles! The terminology you use to describe anything has to be spot on. Tap or Touch? Touch or Select? Tap or Type? Enter or Type? Slide or Drag? Standard key pad or inbuilt? Expand or Enlarge? Popup or Window? Window or Screen? Hold or press? And I have not listed click at all. These are key questions.

The scenario is even more complicated as each device has its own operating system, user interface, icons, navigations methods, and standards.

Currently, Madcap Flare supports Mobile Help output (similar to Webhelp) while RoboHelp provides Mobile output through an eReader.
Flare's output is supposed to work across browsers and multiplatforms - in Blackberry, iPhone, Android, and Windows Mobile (not yet Tablets?). But developers in my project cringed when I said the output would have some JavaScript as Android does not support it. Blackberry too has some image display issues.

So before you plan a user guide or online help for Mobile devices, get your information plan crystal clear.

 Another critical aspect is that users will "search" for information by typing in keywords. Other navigation aids such as TOCs and index won't be so useful.
Therefore, plan your content in such a way that search will yield the desired results.
Flash and heavy graphics may not work well - so user experience designers had better look at HTML and other technologies.
By design these mobile devices will test anyone's patience. These devices are positioned for those on the go - students, working professionals, and fun lovers. Thus, such users will be impatient when they are seeking information.
More on this coming up...

Friday, November 26, 2010

Agile SDLC and some tips for technical writers

Technical documentation is usually written following the SDLC (software development lifecycle) model of the project. The text book DDLC (documentation development lifecycle) fits snugly into the waterfall model. However as customers have moved to a different way of doing and tracking business, they have moved to the Agile SDLC method (for various reasons). Development and testing have been able to follow the Agile method without too much of discomfort. Developing or testing only the selected features is okay as long as the bigger picture of the "Product" is understood. The dependencies of modules, code, and test cases have not really mattered much.

However, things are different for technical writers in the Agile world.

Although a lot of information is available about how documentation fits into the Agile methodology, standard approaches are not yet in place. This is because of these factors:

  • Each product is different and requires different levels of focus from the writers. For example, a complex security or network product might require the writer to learn technical stuff leaving little time for worrying about the approach.
  • Planning might be difficult as requirements might not be clear. Writers might still be looking for basic information about the product
  • Each and every Sprint (a cycle of usually a month that is taken up for development and testing of selected features) is different
  • Documentation approaches for GUI-based manuals contrasts with purely technical explanations (where writers concentrate on 1. how a product is built - the architecture, the workflow, the configuration, deployment, and administration and 2. the technology (high availability, replication, backup, load balancing, Replica management, logging, firewalls, hosting, data recovery, synchronization, and APIs.
  • Writers write well when they have something to say - that is plan a TOC and follow it and ask questions. Agile is about providing just enough documentation for the selected features.

So some of the common approaches that writers working in an Agile SDLC have used are:

  1. Wait till end of Sprint, see if the software GUI is available and then write. Document only what is available. Leave room for more text and planned features.
  2. Plan a TOC to get the big picture (how the document and yes the product will look like). the TOC comes from each feature in the Development or Testing Analysis sheet.
  3. Ensure that document is not PARALLEL to development. Else it will be impossible to write anything.
  4. Topic authoring - write information required for the topic - procedures, concepts, or reference. useful when you don't have any GUI to document the tasks.
  5. Some writers follow a "write once in 2 months" approach. This is a good approach too provided your project management agrees
  6. keep your source diagrams and screen captures in a safe place. You may need to edit these very often.
  7. keep content you write for concepts as technical teams might revert to what you wrote originally. For example, you might have written about database management in the product. The tech reviewer might have felt it was not what they had in mind. then a month later they would say, that it was the same thing they had decided on :)
  8. Ensure that you have a detailed review only every 3 months or so when some parts of the product is froze.
  9. During interim releases or internal betas, give a list of things that you will deliver and no more. Some modules will not have content and that's fine.
  10. if you can, maintain a Doc WIKI and ask the SMEs to collaborate and provide their comments

This should get you started! As you move on, there will be lot more you will learn.