Second Life Forums Archive - why are 'the simple' insructions for setting up scripts rarely simple

Newgate Ludd

Out of Chesse Error

Join date: 8 Apr 2005

Posts: 2,103

06-08-2007 08:58

From: Lasher Oh

One thing I have discovered ( and remeber I am coming art this a a complete layman) is that there seems to be several different ways to skin the same cat.

Actually there are 37......

_____________________

I'm back......

Senuka Harbinger

A-Life, one bit at a time

Join date: 24 Oct 2005

Posts: 491

06-08-2007 20:56

From: Milambus Oh

I don't know about your school, but neither of the ones that I am currently going to offer a class in "Editing a Second Life" notecard. Nor do they offer one titled "SL 099: How to type commands on a specific channel" ... '/1 bling on' is an example of that one, if I was too technical, just so we are clear.

The person you quoted wasn't talking about programming knowledge, but rather knowledge about how Second Life works. Things that yes, we programmers often take for granted.

/QUOTE]

yes, this is the "applied knowledge" That I would -like- to assume people have in SL, but very frequently don't. As a specific example:

I have a product that's used with the CCS combat system to create a quick weapon switching HUD. My initial instructions were fairly straight forward on how to configure a weapon to work with the HUD:

"Drop the script labeled 'Weapon HUD Script' into any CCS weapon with mod permissions (I reccomend renaming a copy first if possible). Then take the modified weapon into your inventory. from your inventory, select the modified weapon, and insert it into the contents of the button you wish to have it hot-keyed to."

I used to recieve several IMs a week from people who couldn't follow those instructions, so I had to go back and rewrite it with the entire "Right click on the object, select edit. click the more button and select the contents tab. open your inventory and find the script labeled...." what was one short paragraph became 3 very long ones to explain every single click, drag, and rename.

For most of the people these extremely detailed instructions will probably be frustrating to read through, but I dare not go back to assumed knowledge anymore for fear of alienating potential customers/users of my products.

_____________________

My SLExchange shop

Typos are forgiven; desecrating the english language with reckless abandon and necrophilic acts is not.

The function is working perfectly fine. It's just not working the way you wanted it to work.

Saijanai Kuhn

Registered User

Join date: 16 May 2007

Posts: 130

06-13-2007 08:21

From: Senuka Harbinger

From: Milambus Oh

[...]

I used to recieve several IMs a week from people who couldn't follow those instructions, so I had to go back and rewrite it with the entire "Right click on the object, select edit. click the more button and select the contents tab. open your inventory and find the script labeled...." what was one short paragraph became 3 very long ones to explain every single click, drag, and rename.

For most of the people these extremely detailed instructions will probably be frustrating to read through, but I dare not go back to assumed knowledge anymore for fear of alienating potential customers/users of my products.

Give a choice: the short version (experienced users) and the long one.

Jake Trenchard

Registered User

Join date: 31 May 2007

Posts: 104

06-13-2007 10:51

One trick to satisfy both camps is to write the instructions outline style.

** Step 1 ** Place the script in your object.
Click the left mouse button on the 'Inventory' button, and scroll through your inventory until you find a folder labeled 'Scripts' ... etc.

** Step 2 ** Set your object 'Modify'
Click the left mouse button on the "Tools" menu item... etc.

The person who knows what they are doing just reads the headlines. The person who doesn't reads each step. Works best in real life printed instructions with large boldface for the outline and you can just scan across the sheet, but it can be somewhat effective even in unformatted computer text.

Monica Balut

Beam-Me

Join date: 18 Feb 2007

Posts: 311

lsl is limited too

06-13-2007 17:07

The Lindens also have to take some responsibility for this also. It's not just the poor dumb user or the nerdy scripter.

If you look at the code in any user oriented software, you'll notice that only about 10% comprises the guts of the program. The rest is about user inferface and code to keep the user from shooting himself in the foot. Most real world languages offer a large variety of ways to allow user input and communication with the program. I haven't been programming in lsl very long, but one of the first things I noticed was how limited the language was, particularly in allowing user input. We are basically restricted to chat, notecards or HUDS. I am usually a stickler about making the program easy for the user but have been frustrated by lsl's dearth of ways to make that happen. If the Lindens spent some time adding better user interface functionality to the language, you'd see a big improvement in the scripts being put out there. I personally would rather see that than sculpties or voice.

Galbraith Karami

Registered User

Join date: 12 Dec 2006

Posts: 25

06-14-2007 01:53

From: Milambus Oh

I don't know about your school, but neither of the ones that I am currently going to offer a class in "Editing a Second Life" notecard. Nor do they offer one titled "SL 099: How to type commands on a specific channel" ... '/1 bling on' is an example of that one, if I was too technical, just so we are clear.

The person you quoted wasn't talking about programming knowledge, but rather knowledge about how Second Life works. Things that yes, we programmers often take for granted.

But is also that knowledge that many newbies never get, cause they're too eager to see the online wordl and jump immediately, without even looking the Orientation Island and such...and so you hear someone ask how do I click on something, or how do I change my clothes. That "class in "Editing a Second Life" notecard" exists, is one of the many stations on the Islands...

Jake Trenchard, that is actually a good idea, I'll have to remember it. Have you been writing those documentations at work?

Monica Balut, I see what you mean, I agree too that LSL has some weirdly missing useful pieces (like arrays, or errorcatch). Just, we were talking about documentation quality, not script quality...

Sam Brodie

Registered User

Join date: 24 May 2004

Posts: 12

07-03-2007 22:04

I have to say, this thread has been very helpful to me, as a scripter-in-learning. And the issue of how to deal with the vast array of folks who may use your work, is daunting, to say the least.

Jake, I love that idea of the outline.. I only have to do one document, instead of several.

Lasher, I agree with you fully except on the few paragraphs thing... I do spend alot of time guiding folks through setups: go to top of screen, Tools, Reset Scripts... err yeah, top of SL screen, left side.... Some folks need volumes, not a couple paragraphs.

why are 'the simple' insructions for setting up scripts rarely simple
Newgate Ludd Out of Chesse Error Join date: 8 Apr 2005 Posts: 2,103	06-08-2007 08:58 From: Lasher Oh One thing I have discovered ( and remeber I am coming art this a a complete layman) is that there seems to be several different ways to skin the same cat. Actually there are 37...... _____________________ I'm back......
Senuka Harbinger A-Life, one bit at a time Join date: 24 Oct 2005 Posts: 491	06-08-2007 20:56 From: Milambus Oh I don't know about your school, but neither of the ones that I am currently going to offer a class in "Editing a Second Life" notecard. Nor do they offer one titled "SL 099: How to type commands on a specific channel" ... '/1 bling on' is an example of that one, if I was too technical, just so we are clear. The person you quoted wasn't talking about programming knowledge, but rather knowledge about how Second Life works. Things that yes, we programmers often take for granted. /QUOTE] yes, this is the "applied knowledge" That I would -like- to assume people have in SL, but very frequently don't. As a specific example: I have a product that's used with the CCS combat system to create a quick weapon switching HUD. My initial instructions were fairly straight forward on how to configure a weapon to work with the HUD: "Drop the script labeled 'Weapon HUD Script' into any CCS weapon with mod permissions (I reccomend renaming a copy first if possible). Then take the modified weapon into your inventory. from your inventory, select the modified weapon, and insert it into the contents of the button you wish to have it hot-keyed to." I used to recieve several IMs a week from people who couldn't follow those instructions, so I had to go back and rewrite it with the entire "Right click on the object, select edit. click the more button and select the contents tab. open your inventory and find the script labeled...." what was one short paragraph became 3 very long ones to explain every single click, drag, and rename. For most of the people these extremely detailed instructions will probably be frustrating to read through, but I dare not go back to assumed knowledge anymore for fear of alienating potential customers/users of my products. _____________________ My SLExchange shop Typos are forgiven; desecrating the english language with reckless abandon and necrophilic acts is not. The function is working perfectly fine. It's just not working the way you wanted it to work.
Saijanai Kuhn Registered User Join date: 16 May 2007 Posts: 130	06-13-2007 08:21 From: Senuka Harbinger From: Milambus Oh [...] I used to recieve several IMs a week from people who couldn't follow those instructions, so I had to go back and rewrite it with the entire "Right click on the object, select edit. click the more button and select the contents tab. open your inventory and find the script labeled...." what was one short paragraph became 3 very long ones to explain every single click, drag, and rename. For most of the people these extremely detailed instructions will probably be frustrating to read through, but I dare not go back to assumed knowledge anymore for fear of alienating potential customers/users of my products. Give a choice: the short version (experienced users) and the long one.
Jake Trenchard Registered User Join date: 31 May 2007 Posts: 104	06-13-2007 10:51 One trick to satisfy both camps is to write the instructions outline style. Step 1 Place the script in your object. Click the left mouse button on the 'Inventory' button, and scroll through your inventory until you find a folder labeled 'Scripts' ... etc. Step 2 Set your object 'Modify' Click the left mouse button on the "Tools" menu item... etc. The person who knows what they are doing just reads the headlines. The person who doesn't reads each step. Works best in real life printed instructions with large boldface for the outline and you can just scan across the sheet, but it can be somewhat effective even in unformatted computer text.
Monica Balut Beam-Me Join date: 18 Feb 2007 Posts: 311	lsl is limited too 06-13-2007 17:07 The Lindens also have to take some responsibility for this also. It's not just the poor dumb user or the nerdy scripter. If you look at the code in any user oriented software, you'll notice that only about 10% comprises the guts of the program. The rest is about user inferface and code to keep the user from shooting himself in the foot. Most real world languages offer a large variety of ways to allow user input and communication with the program. I haven't been programming in lsl very long, but one of the first things I noticed was how limited the language was, particularly in allowing user input. We are basically restricted to chat, notecards or HUDS. I am usually a stickler about making the program easy for the user but have been frustrated by lsl's dearth of ways to make that happen. If the Lindens spent some time adding better user interface functionality to the language, you'd see a big improvement in the scripts being put out there. I personally would rather see that than sculpties or voice.
Galbraith Karami Registered User Join date: 12 Dec 2006 Posts: 25	06-14-2007 01:53 From: Milambus Oh I don't know about your school, but neither of the ones that I am currently going to offer a class in "Editing a Second Life" notecard. Nor do they offer one titled "SL 099: How to type commands on a specific channel" ... '/1 bling on' is an example of that one, if I was too technical, just so we are clear. The person you quoted wasn't talking about programming knowledge, but rather knowledge about how Second Life works. Things that yes, we programmers often take for granted. But is also that knowledge that many newbies never get, cause they're too eager to see the online wordl and jump immediately, without even looking the Orientation Island and such...and so you hear someone ask how do I click on something, or how do I change my clothes. That "class in "Editing a Second Life" notecard" exists, is one of the many stations on the Islands... Jake Trenchard, that is actually a good idea, I'll have to remember it. Have you been writing those documentations at work? Monica Balut, I see what you mean, I agree too that LSL has some weirdly missing useful pieces (like arrays, or errorcatch). Just, we were talking about documentation quality, not script quality...
Sam Brodie Registered User Join date: 24 May 2004 Posts: 12	07-03-2007 22:04 I have to say, this thread has been very helpful to me, as a scripter-in-learning. And the issue of how to deal with the vast array of folks who may use your work, is daunting, to say the least. Jake, I love that idea of the outline.. I only have to do one document, instead of several. Lasher, I agree with you fully except on the few paragraphs thing... I do spend alot of time guiding folks through setups: go to top of screen, Tools, Reset Scripts... err yeah, top of SL screen, left side.... Some folks need volumes, not a couple paragraphs.

Welcome to the Second Life Forums Archive

why are 'the simple' insructions for setting up scripts rarely simple