Comments on eCube: Quick Tips to Create Software Product Tutorials

Submitted on 2009/01/13 at 3:11pm Swati, am glad ...

2010-01-08T13:54:47.241+05:30

Submitted on 2009/01/13 at 3:11pm

Swati, am glad you have brought out a very important point .

Your example illustrates how capitalization plays an important role in writing instructions. Task Pane is so different from task pane. Task Pane is specific and task pane is generic.

You really need to pay so much attention to what tyou write while writing software tutorials. I really appreciate your point.

By the way I wrote Task Pane because that’s how it appears in the tool tip in MS PowerPoint :-)

Submitted on 2009/01/13 at 2:16pm Nice tips, Rupa...

2010-01-08T13:54:13.606+05:30

Submitted on 2009/01/13 at 2:16pm

Nice tips, Rupa. I would extrapolate Tip 7 using the example from Tip 8.

When writing procedures, as you mentioned, it’s extremely important to retain the names of all UI elements as they appear in the application. Towards this end, it’s also important to differentiate between the names of the options the application presents and the generic names of these options. Look at the steps to create a new presentation in PowerPoint once again:

1. Select File -> New from the Main Menu.
2. In the New Presentation Task Pane , choose Blank Presentation.

Here, “File,” “New,” “New Presentation,” and “Blank Presentation” are names of the options in the application UI and “Main Menu” and “Task Pane” are generic names of these options–these are descriptors that qualify the feature as a component of the UI (for example, menu, button, pane, dialog box, text field, commands, and others) but that are not mentioned on the UI. Therefore, it’s important to differentiate between the two and a good way to do this to by writing the application options in initial uppercase (or as they appear in the application UI) and the generic names in lowercase. Going by this rule, the modified procedure would be:
1.
Select File -> New from the main menu.
In the New Presentation task pane, choose Blank Presentation.
This differentiation rules out the possibility of users looking for “Main Menu” or other generic options in the application UI.

Submitted on 2009/01/13 at 12:04pm Hi Ken, Thank ...

2010-01-08T13:53:33.370+05:30

Submitted on 2009/01/13 at 12:04pm

Hi Ken, Thank you for reading my post and appreciating. I also write tutorials for products that are still under development. I just keep updating material. I really need to check the material I write from time to time :-) I appreciate that you make it a point to share your experiences all the time.

Submitted on 2009/01/12 at 3:49pm Kia ora Rupa W...

2010-01-08T13:53:09.776+05:30

Submitted on 2009/01/12 at 3:49pm

Kia ora Rupa

What a neat post! I applaud your need for precision in instruction. Your Tip 7, for instance, is one I put into practice in the late 80s - I wrote instruction tutorials for software use then. But I also gave the courses, and the tutorials I wrote were the course tutorials too - so they had to be right. What you say about getting the terminology so correct is spot on. I’d go further and say it should actually look in the instruction exactly as it appears in the app.

From time to time I was required to write tutorials for software that wasn’t built yet - vapourware we used to call it. That was a hard call. I used to draft the tutorial and fill in the details when I got my hands on the final draft of the app - not a comfortable job - but that’s life.

Catchya later
from Middle-earth

Submitted on 2009/01/09 at 1:54pm That was a good...

2010-01-08T13:52:49.827+05:30

Submitted on 2009/01/09 at 1:54pm

That was a good tip Manish. I usually put the alternative ways to complete the task as a note.Hope to see more tips here :-)

Submitted on 2009/01/09 at 1:48pm Great tips Rupa...

2010-01-08T13:52:28.676+05:30

Submitted on 2009/01/09 at 1:48pm

Great tips Rupa. Thanks.

Adding to your tips:
10. When there is more than one way to complete a task, teach about the most commonly used method. You may provide other methods as additional info or as an additional tip for the learners.

Would love the readers to add more tips to create software product tutorials.