User Script Reference? (the first poll)

This got started here and I think it's a good idea but it will be a little work for some one to transfer the existing refrence to a wiki (I will do it). The advantage of doing it in a user wiki is any one whos any one can add examples, notes, ect. Joachim said that he will give accounts to there reference wiki if people want to add stuff. My feeling is that some times having to go through the "man" (no offense) is not encouraging.

-Bill

 

"the man" put that School of Rock scene in my head ...anyway...

Once it's underway I'd contribute. Mostly questions at first, sprinkled with requests for examples I'm sure. But then that would be the beauty of it, I think...Anyone could come by and pose questions, requests or whatever.

As a newb I wouldn't dare sign up to use "the man's" wiki. Even if I was specifically invited to come and mark things I didn't understand (/make a mess) I'd still be shy/cautious about it.

When it's by us for us..it's just...different.

 

Thats also what I thought.

-Bill

 

I see where you guys are coming from and I don't want to sound argumentative, but... I just don't think it makes a lot of sense to have redundant information with different sets of example code. Because, frankly, the Unity guys will update theirs and you guys will update yours and then there's two twisted paths. Which one is more useful to look at? How do you explain the difference to new users?

Wiki's are great because people can tweak and improve elements that are already there. If you make some example code that is mostly good with a couple conceptual errors it can be tweaked by someone with a little more experience.

I say keep it all in one place.

The one part of this that might be tricky is making the updated reference material available quickly to everyone as things are added.

Then there is this straight-up question to answer:
If anyone is too worried that their code examples aren't good enough to hold up to scrutiny why are we interested in their code examples?

 

Good point, I agree, might be redundent... but like iamBob said when it's by us for us it's just different.

-Bill

 

aaron...

The information may be redundant at first but I wouldn't expect it to stay that way for too long. If anyone can and does edit it..change happens. Get a little discussion going [why do we need this page? because. well, what if we did this or refactored that?] and who knows where it could go. I think all you'd have to do is grab a few eyes and a bit of interest and it'd grow (or shrink, whatever..wiki rules) over time.

Just because otee updates theirs doesn't mean our version would need any more updating than usual. There may or may not be "twisted paths", both could be useful and I doubt many people would confuse the wiki with official otee docs.

Simple. Given some poor examples we might be able to figure out what needs clarification. Besides, if they're that bad they'll get fixed, removed or refactored eventually...no biggy.

-Ryan

 

I think Joachim said stuff goes into the private OTEE wiki (if he gives you an account) and then makes its way to the Documentation. So there's someone in between editing the content (someone at OTEE). I think it's a good idea.

And thanks sync for getting polls started, they're always fun :wink:

 

Well, hey 8)

I dont think it will be very redundant after it gets started. We probably wont copy EVERY THING. Just the stuff we think could use better examples.

Also even if it is redundant ill be the one doing the heavy lifting (i.e. work)

-Bill

 

I don't think there's any redundancy since 75% of the Scripting References don't have any examples. I'd just like to see simple 5 lines of code saying "this is how this function is implemented". Certain things will be redundant in the same class, but who cares, give newbies a fighting chance :wink:

 

At the moment, the reference is just autogenerated from the wiki using some weird perl scripts ;-) We do read it through before doing so... Don't know if that counts as "editing"...

One thing I've been considering; How about enabling public comments? That way newbies can point out stuff, but it won't get pulled into the main docs... some more experienced users can then take the comments and put into the documentation. So in a way, the comments would work as a staging area...

Could this work?

 

I think it could, but there might be a lot of comments. Not that thats really a problem. How would we put it into the documentation? Would we still have to _ask_ :wink: for a account, and can you make the entire script refrence available to comment. I know joachim said that only the How-to's were editable.

-Bill

 

The How-TOs, User Guide Component reference are accessible from the wiki...

I was thinking to allow public comments, and then a group of people who have editing access to the manual.

If you look at http://www.php.net/manual/en/language.expressions.php you can see that php is not overloaded with comments - and they do have quite a larger userbase than us ;-)

Also, back in my php coding days, I used the comments a lot - the reference gave the spec, and the comments gave all the weird workarounds and tricks...

 

Right, I understand the beauty of wikis. But why two wiki's? Your contention should be equally true in the wiki that already exists. Why make a wiki specifically for people not confident enough to put examples in the original wiki?

Don't get me wrong, though! I'm not against people new to Unity and programming giving input and providing their fresh perspective. Understanding the barriers to new users is extremely important in the further development of Unity. I just disagree with the particulars being discussed.

To me, the core issue is getting more code examples into the docs more quickly. That I can get behind.

It looks like nicholas is on the right track here. I like his idea. Anyone could simply add a code example to the comments, and then it could be wrestled with if there are any issues and then, it could be added in by a more experienced programmer if "approved." In addition, all the questions and workarounds could be discussed under it.

Doesn't that satisfy everyone's needs?

 

The problem is that the scripting reference is NOT in a wiki. It's embedded in our source code, mixed with implementation details...

So we need something for the scripting - how about just creating a new area on the existing unify wiki. When the format has settled, we can go through the code for inclusion into Unity.

 

This confused me from the other thread. So, many of my points are moot. Sorry if I confused the issue.

I think I get it, now. (What, exactly, is on the internal wiki, then?)

So, add a script reference branch on the unify wiki, then. Eventually that info would somehow get back to the real script reference? Or will it become it? Or will it be a mish-mosh editing job for some poor soul? Or could a clever perl coder save the day?

One thing that is important, I think, is that the ENTIRE script reference is put on the unify wiki with all current examples. The starting point should at least be equal.

 

Why not a new folder/topic on the forum but only visible to log in users and once the code is bug free can be added to the existing wiki or to Unity docs as an example.

Ray

 

I hadn't thought of that, good idea Ray!

Only a couple downsides (off-the-top) that I can see;
1) On a wiki there's (usually) anonymity* by default and that may be important to some people.

2) You'd have to specify where your example fits if it's not immediately obvious.

Still, it would be a lot easier to make a new forum topic.

*or as close to it as you can get.

 

Well where does this leave us then? Right now using the otee wiki is leading, but these other ideas are good to... We should decide some thing...

Bill

 

Some thing, any thing!

Bill

 

it's just starting to sound a little convoluted at the moment... "post to weirdo commented private otee wiki where stuff might get into the public docs"? this project needs a definite venue, and maybe the unedited wiki provided by jeff is the solution. it's just a matter of saying "jeff's site/wiki is the defacto place to go for user based Unity documentation/tutorials." i'm all for it, jeff's stepped up to the challenge and created such a place, so let's use it to it's fullest (if that's ok with jeff). as long as the wiki is searchable it's as good as finding something in the docs with the added benefit of an actual example of the syntax involved of what you might be trying to achieve... and multiple syntax examples can be added to each wiki entry. within a couple of months we could replicate the whole script docs with user added examples... sounds good to me.

 

Feel free to use the snippet wiki, I put it up with the intention of all being able to add to it and make it become a very complete reference, and so on. Jeff