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

Quite a few time now I have bought objects such as doors and teleporters and quite a few other things beside all on the premise that they have easy to set up and understand instructions...needless this is a false claim and after tinkering around getting nowhere for at least a couple of hours I retreat feeling like a fool.

Questions

Is there a 'understanding scripts for dummy's place I can go to or should I just throw my computer out the window because I'm too dumb to own one if I cant understand what comes naturally to a techy head?

Why in the instructions don't the script writers show actual copy paste examples (perhaps with a colour variation that indicates 'your name goes here in this format?

Are these things that are just second nature to the techies and therefore they feel everyone should see the bleedin' obvious.?

So now I have all these cute gadgets and personalized items that are just sitting there unused... what a shame as the writers would clearly like their work to work for others I would expect .

Thx in advance for being patient while I vent, but heck I've been stuck with these problems for a few weeks now and just when I think I have it sussed it all comes back to bite me on the bum

Lasher Oh

Your best bet usually is to talk to the creators. If you can't understand it, or the guide/readme doesn't help then unfortunately it's a poorly designed product.

There's no one way to set-up a script, and few are ever the same

This can actually be a lot more difficult than it sounds. Sometimes people can ask questions way outside of anything you can possibly image. It is also not wholly unreasonable for a product creator to assume a basic understanding of How Things Work in Second Life. Basically, you're catering for a very broad spectrum of potential users - not all of which necessarily even speak English.

Because I was getting asked such a diverse range of question for a particular device - anything from queries with editing notecards to debugging other people's command usage on their products - I eventually made a web site: http://www.pixelportal.demon.co.uk/SL/intro.htm. This is quite a time consuming exercise.

You might find the first couple of sections useful as they attempt to cover some of the basic stuff generic to lots of 'gadgets' that often isn't documented but assumed.

One thing I am disappointed about, however, is how little useful feedback people give on products. A few ask what I often feel are pretty basic questions, but very, very, few people give a simple heads-up on a problem they have encountered, or make suggestions on how you might improve a product.

And, yes, a good content creator *should* be responsive to you directly contacting them for help.

I know if the few products I have, I try and make the readme/instructions clear, by passing it to a friend and having them set it up. Unfortunately, it seems most people just put out the product, and expect it to work, instead of taking the time to actually look at the notecards provided. I've been asked several times about a simple question that is explained in the notecard quite clearly, which can get irritating to content creators if they are asked the same question over and over again, when it's clearly already explained. So if you are having problems with a product of any kind, make sure you have read the instructions first, fully, then contact the creator with your question.

I hate to say the opposite thing...

...but I'm often surprised at the kinds of questions I'm asked when someone buys my scripts. Doors, for instance, require a person only to be able to click on the door and then on one of several configuration buttons...and that's it. Yet, I still get questions of "I don't understand how to press the button".

Yes, part of the problem is that techies spend so much time with tech that we sometimes forget how foreign it is to people. Another part of hte problem is that it's hard to remember what it's like to be a newbie in SecondLife. Finally, a third problem is that many scripts out there are not geared toward ease-of-use, but rather quickness-of-scripting. See...as a programmer on SL I can hope to make, oh, US$4/hr....whereas as a programmer in RL I can make, oh, US$100/hr. Why should I spend time and effort on programming in SL when I can feed myself MUCH better and with MUCH less effort by programming in RL?

That said...there ARE those of us who go to great lengths to attempt to make scripts easy to use and who always respond to help requests. I personally spend about 2 hours per day helping people to understand even the most basic functions of SL so that they may have a better experience.

I'm currently trying to make as many of my products dialog or HUD based. HUDs are especially great for complex items as you can give simple, iconic representations of commands, which is often better (if your icons are good anyway). You can also mimic computer operating system behaviour to some extent.

This would be easier if slider bars were easier to do, but as mentioned in my thread the values given when trying to do it are often nonsensical:
/54/1d/186955/1.html

It just IS hard to "lower" yourself to the computer knowledge of the user, really. Things you've taken for granted for ages already are probably still complete abracadabra for anyone who doesn't have any scripting or programming experience. And of course, some limitations within SL don't really help either. Would be nice if we had input fields other then the chat bar for example, or were able to actually write notecards. But as SL is now, any customization of a script has to be done through either a noteard or directly in the script. Both of which aren't too great methods for people who lack programming skills.
One common reason why many scripters put their work on non-modify isn't just because they want to keep their work a secret and copyprotected.. It's because some customers like to fiddle with scripts without much programming knowledge, probably breaking parts of the script or adding other new parts, and the one who's asked to fix it is... yes, the original programmer, who might not even recognize it anymore after all the changes it's undergone since he parted with it.

I think this wholly depends on the creator/author of the item.

For example, I built a mini steam train ride for someone. It is a tad complicated to set up in its initial version, but I sat down and wrote a complete step-by-step manual for doing so, complete with explanations why things work the way they do for the layman. The manual is easily as long as all the scripts in the ride combined, if not longer. Not many folks go to that much trouble, but I have written software for various industries for a long long time, and have written user documents for much of it as a requirement in that time, so I learned how to do it right.

As a user myself, I appreciate the value of good documentation. I read EVERY THING about a product I can, including experiences of other users, before I ever try to contact support. Once in a while I miss something obvious, but not often, and I rarely have to contact the developer(s) for assistance. Thus, the better the initial documentation, the more empowered I am to solve my own problems with a product.

Ultimately it boils down to a few main issues (several of which have already been pointed out):

1) Many creators are inexperienced with creating things, and don't understand the value of making them user-friendly (or work well, for that matter).
2) Many creators underestimate the value of good documentation and/or support.
3) Many consumers are terminally lazy, and refuse to perform the bare minimum of due diligence to help themselves first.
4) Second Life is a hobby to many people and, thus, the amount of effort people are willing to put into performing due diligence on either the producer's or consumer's (or both) side of the equation is very small, thus resulting in any/all of the above.

You'll note that nowhere in that list will you find "users who are tech-dumb" or "ignorant". Those are not reasons, nor excuses, for a bad product experience. EVERYone is ignorant of everything in their life until they learn and/or experience it. Creators should always remember that when they make their creations. Consumers should always remember that, because it takes effort to learn and experience. There's no "download knowledge and wisdom" button, even in SL, at least when it comes to getting it through the granite into the wetware.

Well, i understand the problem.. not being totally conversant with SL scripting, but have my head screwed on enough to use the finished item and the key parts... i learned Iptscrae a long time ago and have delved into bits and bobs..not being perfect doesnt mean one is stupid..

What kinda beats me though is when like now, someone who really does know their stuff, posts a script, complete ready to go.. one would think.. like this one..

Bucky's Radio - 2.6.4

a free radio script that one can copy would be really usefull to me right now.. and this one looked exactly what i wanted..

EXCEPT its not written in something SL understands.. if i post the script in an object, i get a syntax error.. because it has this header

SL doesnt know what that is.. neither do i, so the script is trash to me, i cant use it..

All the work that author took is wasted on me.. simply because its unuseable ..

i can get a radio.. 150 lindens  is no big deal.. but i cant copy it.. modify or change.. so.. my learning window is shut if i buy one...because i learn backwards, i start with a working finished something and pull it apart to see what makes it tick..

but.. if someone offers a free script.. one would expect that it would run in SL.. or is that not the reason we are here in forumns?

if someone knows what i need to do to get bucky`s script working in an SL prim i would appreciate that.. bucky wont take e mail, i cant reach him.. 

all the doors are closed.. :(

Errr that script compiled fine, exactly what caused your problem?
You do realise that [ code ] [ /code ] is an alternative BB code ?

you can thank the retard lindens for that, theres something on this forum called bbcode that [code ] header (and footer) is for the forums, it displays the script in its own seperate little space like a quote

sometime before the holiday they shut all that off for a "upgrade" that they havent done and never turned it back on

Thank You Osgeld, that explains why i see this, Newgate..

ive no idea why yours compiles and mine gets an error Newgate.. but its there.. a syntax error caused by

, i get the same error if the header is 
CODE

example..
CODE

//------------------------RADIO STATION CHANGER------------------------------
//
// By: Kenn Nilsson and Jesrad Seraph
// Updated: 10/17/05
// Version: 0.2
//
//---------------------------------------------------------------------------

string card;
integer line;
key query; 

ETC...
gets this  (0,0):Syntax error

ok.. i figured that deleting that header and footer cures the problem.. and it does..

But you can see now Newgate, how easy it is for something that WAS fine.. becomes unuseable, and why folks get really wound up when someone says,

"Errr that script compiled fine, exactly what caused your problem?
You do realise that [ code ] [ /code ] is an alternative BB code ?"

i see what i see, Syntax error.. its nothing to do with my realisation. i realise fine, thank you..:)

Actually, no you do not. If you realize/were aware that those were BB (or Bulletin board) tags, then you should have known to remove them when trying to use the script in SL.

Now Newgate probably could have stated it a bit more clearly, as Osgeld later did. And perhaps this is a language barrier thing.

This is a perfect example of what this thread is discussing in the first place. Yes, we techies/scripters do need to realize that not everyone has as much of an understanding of how the game works as we do. But users also need to try to gain some basic understanding of the environment in which they are interacting.

In the case of the forums and the problem of the [ code ] blocks not displaying as they should, all it takes is one question to get an answer. Or if you look at the top of the forum you will see a post by one of the Lindens that says why the BBCodes are not working correctly. Of course that post may have been too technical to do you any good, in which case asking was the better route.

I'll agree with both the 'users' and the 'scripters' here. In my experience, writing a script that does what I want it to, with lots of bells and whistles, is the easy part. I *like* this part -- it's fun to script and make things happen in SL.

The part that is painful, horribly difficult, and frankly not very enjoyable to me, is both developing a good user interface and writing clear documentation, that makes a script usable by the general public. This part is so incredibly important, and yet such a pain, that I personally have lots of little code snippets that do kinda cool and/or useful things, but will NEVER be seen by anyone else, simply because it's not worth the effort to 'package it' right.




[ /me has just gotten finished writing an 8-part set of lessons, FAQ / troubleshooting, tips + tricks, and command summary, to describe how to use his latest project... and it STILL probably won't be enough ]

Hey Lasher, would you happen to be my neighbor in SL? I live just north of a 'Lasher Mountain' plot if I recall.

The script thing is definitely a learning curve for somebody who hasn't programmed before. SL is chalk FULL of geeks and in general this throws off the curve of what the average joe here finds 'easy'.

There are some very introductory tutorials out there that can help you through just getting the look and feel of the script interface so that you aren't tripping over it when you actually sit down to modify an existing script. Try reading through both of these:
http://rpgstats.com/wiki/index.php?title=LSL101
http://www.kan-ed.org/second-life/using-LSL.html

Also to your other point, a script (or any program in anly language) can contain 'comments'. That is the stuff after the // marks in the script which is just a way for the writer to leave notes, explanation, instructions for anyone reading the script. A GOOD script will contain plenty of these and make it much easier for you to understand what is what.

Programming is really an art. Anybody can write a script, but few can really write a readable, easy to use, and self-documenting script.

I have to agree with the bulk of this post. There are far too many scripter's in Second Life that do not implement a standardized documentation. As a scripter myself, I understand that full documentation can be very time-consuming. In fact, I spend more time on the documentation than I do on the scripts themselves.

I do believe there should be some form of standardization of scripts. I do not believe that everyone should be required to follow my system ( I am kind of anal about documentation ), but I do believe that some form of standard should be introduced. Be it notecard support, or within the scripts themselves. (If you would like to see some of my documentation, check out my thread on my Wishing Well script. If you would like to find out more about my documentation system, variable naming conventions, and script setup system, please contact me in-world.)

I try to make all my products as easy to use out of the box as possible. And I am always willing to help other people out with their scripts if I have the time to do so. If you need assistance, go ahead and send me an IM. I may not reply right away, but I will eventually reply.

I find quite frequently in my experience that many people asking me for some simple scripting jobs, such as doors with a limited access list (via note-card), or a simple color change on command script (via menu or chat channel), have been on a 100% track record for not knowing how to perform what I consider basic SL skills such as editing a note-card, or reading and clicking on buttons in a dialogue menu (shocking, yes).

Now that I have progressed a significant amount into my first wide-scale marketable project, I've been getting comments from some of my beta testers that my documentation "Dumbs things down too much" because I'm trying to accomodate for the types of SL users mentioned above. I have been working on an "advanced user" guide for my product that assumes more about the user's knowledge of SL to help reduce the sheer reading amount involved with the dumbed down version.

Unfortunately this is extremely tedious and frustrating on my end because I feel like I'm being forced to take extra steps (an extremely long and dumbed down instruction manual) because of other users' ignorance and/or refusal to learn/apply knowledge that they have encountered before.

Thanky ou all for contributing to this very helpful thread, and your responses were both illuminating , and I have to say confounding, yes there was a little dip into geek speak aroud the radio issue which had my eyes glazing over.

In the interim period I have taken myself a little deeper into the world of scripting, I didn't really want to do this as it is not my sphere of expertise I prefer to make the pretty pictures rather than the magic carpets. 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. When I had a look at several different scripts for the same function in order to kind of reverse engineer I discovered that some bits of code were placed in different places from others...so nothing standard that I could get a fix on and jeez all this trouble just to get a door to close on the right coordinates or my name to show with a different colour. Do I havcce to kee the text inside double quotes and do I need to repeat at the top as well as the bottom and...I could go on

As you see I'm not talking the rocket science which I sit back and look at with awe and admiration and I have much empathy with all the scripters who enjoy the 'making' it's a creative thing and as a designer I often find that explaining and selling the concepts to a client is much harder than cracking the problem they gave me. But as a commercial designer whenever I start a project and before I even put pen to paper, my first consideration is not a demonstration of my wit and skill, nor is it fulfilling or interpretating my clients puzzles, but it is for the end user the Joe and Jane Soaps at the end of the line who has to buy into my concept and who definitely don't give a shit about how the product was made other than does it work for them and is the price right.

So the only point made that I take issue with is one....

"//Unfortunately this is extremely tedious and frustrating on my end because I feel like I'm being forced to take extra steps (an extremely long and dumbed down instruction manual) because of other users' ignorance and/or refusal to learn/apply knowledge that they have encountered before.\\"

Surely that 'knowledge' referred to has been aquired and learnt either through lengthy college education or by clicking through page after page of manuals and tutorials. If I had wanted to be a programmer I would have followed that path, but all I really want is to buy a door and put my details into the script which I have have been sold without having to go and take a lenghty induction course in scripting lanquage. Or send a load of email IMs back and forth to pester the writer.

So as one one of those great unwashed 'ignorant' users I have to ask you if you feel we should all learn a little bit of everyone elses professions? And I have this little observation on 'manuals' the time taken to explain things simply and concisely is worth it's weight in gold and I can assure the shorter the better. If you've written a script yhat takes more than a couple of paragraphs to explain then something isn't right.

SL is inevitably heavily populated by 'industry' professionals all eager to show of their skills and impress their peers, and a few even seem to have assumed olympian status with regard to serfs like me who still crap and pee, but as a consumer I know that my next perchase will be from a vendor who sold me a product that does what it said on the box, and as for those that challenge my valuable time... well I'm sure they are good products but better left for those who have the 'knowledge"

Hi Shadow, you're right "Lasher's Mountain' that's mine

Thanks for the links and the encouragement. I've only been 2 months in SL and my brain is still spinning, there's so much to learns and I have been earning very very hard. It's difficult enough understanding and using prims without having to go take a Linden Scripting 101 course at the same time but it seems both go hand in hand.

I'm not complaining though, as in the last two months I've learnt new photoshop skills which will put me in good staed for the future in 1st Life too and even a basic understanding of 'programming will help me stand my ground in the pub when one of my programmer pals trys to baffle me with science

If your ever flying past the mountain please drop in and for a chat

Lasher ^L^

As you may have discovered programming is as much an Art as it is a Science. Our Art simply has words like "If", "Else" and "Switch" as its components where yours has brushes (real or virtual), pigments and a canvas. Its still the act of creation, its just done in different ways.

Just as there are different ways to draw a circle, there are many different ways to store a representation of that circle into memory. Picking the right way to do something is what separates a good programmer/designer from the bad ones.



And how much do you charge per hour for your design skills? I personally charge $35-50 for freelance work.. and thats very cheap for the work that I do. Now lets say one were to charge 250 lindens (roughly $1 US) for the script.. I would have to sell 35 copies of the script for every hour I spent creating it. Which really isn't very likely, unless all you ever made were very simple little scripts.



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.



Truthfully, yes. As a program -I- have to know at least a little bit about how everything else works, so I don't think its too out of place for you as a designer to have some base knowledge of how scripts work.



Simple and concise means different things to different people. Zero instructions is very simple and very concise... but not very helpful now is it?

And as for taking more than a couple of paragraphs.. well perhaps if you're talking about a bling script.. or a Title setter. But the more complicated the script is, the more complicated the instructions will be.

I think you are not the type of user for whom the long manual is written. There are users out there who understand very well how to use the GUI parts of a computer but know nothing about programming, have no understanding of the professional side of things, but they can be told, in the Windows world, 'Open the WhizBang(tm) control panel item ... ' and they are on their way. Other users need to be told, "From the windows desktop, click the left mouse button on the start button, and then click the left mouse button on "Control Panel". A window will open, displaying many icons. Find the blue icon with the yellow lightning bolt (see Fig 1) labeled 'WhizBang(tm) Settings'. Double-click this icon with the left mouse button.' They will need instructions like this -despite- having used a computer for years.

For many people, it seems to be impossible to abstract the common themes in configuring and using software. (Lest anyone try to stereotype who those people are, my grandmother is very computer savvy, and my nephew is hopeless, by the by.) This is why real software manuals are so long and hard to read, and why they often come with all of the 'quick start guide', the 'installation manual', the 'user's manual' and the 'reference manual'. There needs to be both easy ways to access the important information, and step-by-step handholding instructions. Not having one or the other is going to cost customers.

Note, there is a third kind of documentation, the technical document, that instantly details parameters, assumes you know all sorts of things only a professional programmer would know and gives only the technical specifications - maybe to the extreme of only tables of numbers labeled with short acronyms. This kind of documentation should never be the documentation for an end user product, but sometimes it is the only kind of documentation that the programmer knows how to write.

I haven't seen the whole range of what's in SL, but I have a feeling it isn't much different from real life, if more like real life some years ago when software was a wilder industry with more 1- and 2-man shops. Some people will understand, 'Wear the object... ' and some people will need "In the lower-right corner of the game window, click on the button marked 'Inventory' ... "

It has to be said, that fault can be on both sides. I do LSL scripting, and I've examined freebie objects, as well as read documentation, make scripted objects of my own and do their documentation. But for some time I've also been a greeter in a public place, where newbies were common due to a nearby welcome area...
What can I say? That all depends on people: sometimes is the user's fault, sometimes it's the creator's. I've looked inside a freebie gun and saw it was using the classic popgun script; looked in the popgun, only to discover that it was a butchered modification of a bow-and-arrow script, in a way that comments and such made very little sense.
And with all the newbies I've met, I've come to the conclusion that some are just dumb, or too lazy to even try to understand how to use the "game" they're in. They just jump from their rez point in main land skipping any help or orientation area, and then complain because it's boring, they don't understand it, and you can just see they don't even know how to do the most basic things. But be it innocent ignorance, PC incompetence or mental lazyness, that kind of users would be lost even with "buy clothes > rez box > open it and click Copy to Inventory".
I've seen objects with few lines or pages and pages of manual, making it equally hard to use their stuff...
On my part, I tend to make easy-to-use interfaces cause *I* use them and it'd be a pain in the rear, and write simple, clear instructions so anyone can use them. (that is, anyone with a minimal knowledge of SL functions...)
In the end, you try to do your best: you write good documentation, and offer assistance to those that for whatever reasons can't use the item. As with real PC, there will always be the geek expert that installs and configures hardware without even looking at the manual, and the clueless dude that can't even find it...

Reading someone's code is a lot like reading a persons' handwriting. After a while you may even start to recognize who wrote a script, just by glancing at it. I used to do live-bugfixing and hop in on projects that were at the final stage a few years back, and after a year I could recognize the code of most of my 30 collegues.
This also means that 2 scripters might code exactly the same thing, almost following the same "flow" even, but 1 script being readable for a novice, the other seeming completely unintelligeble. You probably already noticed how some people use a lot of tabs at the start of a line, while others don't. Or how some scripters have a lot of 1-digit things in their code (a, b, c), where others use something longer like: intThisIsTheAmountOfSomethingIWannaKeepTrackOf
or: strThisIsWhatWhoeverJustTypedInChat.

Lasher, if you paid money for a script that was meant to be configurable then you probably have some grounds for a peeve, but ultimately, a lot of stuff like that is "some assembly required" and the creator may have assumed that the only people who'd be editing an LSL script are people who want to edit an LSL script.