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.
- 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.
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…
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:
- 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.
- 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.
- Ensure that document is not PARALLEL to development. Else it will be impossible to write anything.
- Topic authoring – write information required for the topic – procedures, concepts, or reference. useful when you don’t have any GUI to document the tasks.
- Some writers follow a “write once in 2 months” approach. This is a good approach too provided your project management agrees
- keep your source diagrams and screen captures in a safe place. You may need to edit these very often.
- 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 🙂
- Ensure that you have a detailed review only every 3 months or so when some parts of the product is froze.
- 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.
- 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.
A new writer joined our project recently. She mentioned that she had attended an interview at a leading product (anti-virus) company and was asked to explain “Reflexive Pronouns”. Well it is a pronoun – used instead of an antecedent noun or pronoun (example He, She instead of Bill or Tom) but it is emphasized. For example “he himself” or “she herself”…
So the question is: why did the interviewer ask such a question? Technical writers need not know the explanation or details of Grammar to such an extent. Do the technical writers in that company think about Grammar when they write user manuals and online help? If a writer knew how to write correctly without ever thinking of Grammar, I am fine with it. Years ago, I too was asked a question by a poorly trained interviewer “what is a Gerund”. I said “It is a verb with ing form”. She said “No you are wrong!” I found that it is a noun with ing form. But why does it matter? It should not. I can write very well (am sure much better than the interviewer) and I know no grammar (American slang :)).
Is there an ulterior motive here? Or are the interviewers just unprofessional? Knowing the country and its technical writers I think it is the former…
Time the interviews were recorded as they do with the Cambridge exams for example. Time the questions and hiring methods were standardized. Give them a written test please.
I wanted to move over to a touch screen mobile and bought the Sony Ericsson XPERIA Mini Pro as it looked stylish and cost less thanks to some “offer”. Moreover, I was excited with the Android OS. However, I made a bloody mistake and did not check out the usability of the touch screen enabled navigation. I was yes new to touch screens and had assumed that I would get what I had all along been used to with a normal keypad mobile phone.
In the name of making the application modern, the whole navigation has been made difficult. Let me provide two examples:
1. I want to save a number from the call log under a new contact. I expect to just tap the number and get an option to save it. However tap dials the number which is rather irritating although cool. Yes that’s a fundamental problem with touch screens I accept – but I cannot understand why they have not provided an icon that would give me a list of options. The + sign icon for add is not self explanatory. To save a contact from a log list I need to do these:
– Open the touch keypad
– Click + next to a number in the call log
– A new screen appears (says Search on top and I get confused) where I have to again select another + sign (with face image)
– Then I have to type in the contact name and save. However, the conatct is still saved without a name when I use the back button on the “hardware mobile”. The plus sign disappears although I have not yet saved the contact under a name 😦
So the application is a bit tough to get used to. I need Help to understand…
Being a technical writer, I thought I would check out the phone’s mobile help. I found an “user guide” but the Help item for the above scenario is not easy to find. I used search to find the answer.
The Help topic for this is listed under Contents > Calling > Call Handling.
A procedure head says “To add a contact from the call log”.
I think this topic should be under Contacts > Dialling and Saving Contacts. It should also be under “Call Logs” (which I don’t find anywhere on the Contents).
This topic should also be under FAQs. Yes you could hyperlink the topic from Call Handling too.
Here, I was looking for convenience. I should be able to quickly save a number as a new contact – maybe using only my left hand while traveling or driving as my other hand is not free. The way the application made me go around was bad. The Help was not easy to find too as the author must have thought from a system perspective.
2. I don’t use SMS so much. They are better for students/kiddos as text messaging is cheaper. Yes it helps when you are in a meeting and can’t talk but still want to convey. Or when you don’t want to call. But SMS using touch screen is a bit cumbersome. I did not find the obvious “Reply” option when I tap a message. So I open the Help and go to User Guide > Messaging > SMS and MMS > Using SMS and MMS and I find a procedure “Reply to message sender”. I have to tap a message and then select “write message”. Instead the Help says “Tap the text field”. How do I know which is the text field?
Why not a simple Reply item?
Why does not Help specify this: Tap the area where it says “write message”?
Finally, I managed to find the screen lock (press the power off/on switch once). Once the touch screen did not respond when I touched it but worked after sometime.
All in all a disappointing mobile with unfriendly navigation. Help is also poorly structured. I wish the authors had done a better analysis of the users and scenarios. At least they could have explained the icons and navigation better. In fact they should use a few more icons – for instance when I see an entry in the call log, I know if I touch it, I would dial the contact or number. So if I wanted to delete the log item quickly … all I need to touch is a simple delete icon. Currently, I have to keep pressing the contact carefully to launch the options.