Frustrations with Biki

[sbsmac 0]

I've posted this in 'Mission Editing and Scripting' because my comments mainly apply to the scripting reference on Biki. I find myself often using this resource to try and find out about commands. Many pages seem to lack detail and though I'm often tempted to do a bit of editing, I usually back out of making the effort. In trying to figure out why I don't contribute more I identified a few areas.

1) I find the format a bit illogical for a command reference. Most programmer's references start with a one line description of the command, follow it up with syntax, then have a paragraph or two of detail. Biki seems not to follow this convention.

2) The use of the 'Notes' section just encourages people (when they do contribute) to turn the pages into a random sequence of facts rather than a coherent description.

3) The pages are templatised to death - editing them is a nightmare and it's difficult to get sensible rendering for slightly non-standard information. Example - I tried merging the two CreateUnit pages to bring all the information together in one place but immediately ran into problems trying to indicate the command worked for both games.

4) The "DO NOT POST QUESTIONS HERE" policy makes it difficult to contribute sensibly. Biki is a place to go for answers but it's difficult to know what answers to provide when you're not even allowed to see the questions ! More to the point, there are some questions that only BIS can answer - if they want the community to fill in the documentation, they have to allow some things to be asked.

Rant over ....

[Big Dawg KS 6]

1. The format is appropriate for a wiki, and there's nothing wrong with the descriptions. You can't expect a paragraph long description for EVERY command, and you can only really go into such detail with very few of them. Also, that's why there are notes.

2. The notes, well as they're called notes they would be just that; a random sequence of facts. If people leave good notes it's up to them, but the purpose of the notes is for people to add discovered facts that aren't included in the description when they find them.

3. If you're not an expert on the commands you shouldn't be editing the pages, and especially not something as drastic as merging two pages, and if you need to add information you can use the notes.

4. You read it wrong, it says don't ask questions in the notes. If everyone asked questions it would clutter the page, which should contain only facts that are useful and clear to the reader. Like on these forums, searching through a ton of questions and responses to find information is very inconvenient. You can ask questions in the talk page (where it is appropriate to discuss the contents of the article) or here on the forums where you are more likely to get a response. I think you have the wrong idea about the wiki, it's a database that contains facts, questions are for forums and places where there are people there to respond to you. The wiki should be a reference/resource, not a place of discussion (that's what forums are for). Also, the information on the wiki is added mainly by community members, and it's certainly not the right place to contact BIS. You should contact BIS directly if you want answers, and if BIS has something important to add to the wiki they'd certainly add it or have someone add it.

Like I said many times, the wiki is appropriate for what it's supposed to be, it's certainly not the only place to find information on commands, and it's not meant to contain every single fact everyone would ever want to know. If you can't find information the best thing to do is ask on the forums, where you're sure to at least get some response, and it's likely to be the answer you're looking for.

[fasad 1]

I've found the command descriptions are very useful, but a command reference is very hard to make use of unless you are already familiar with the commands. This can makes the wiki beginner unfriendly - they have to learn what each command does before considering which command is best to solve a problem. This seems to scare most people off, which is why basic command syntax questions still get asked here.

It seems the commands are being grouped into functionality : Scripting Commands by Function.

The no questions rule helps keep the wiki clean and factual, but it does reduces the speed at which info has been added. I've been trying to add to the commands as I refer to them.

[pyro05x 0]

I find the BI Wiki very useful...useful enough for me to make a search plugin for Firefox. I prefer it over the OFPEC com ref, which is very ugly and harder to navigate than any wiki.

I do believe that beginners do have a lot of trouble if they don't have any prior programming experience (minimum VB, recommended c/c++). I'm one of those who's never edited for OFP or even played OFP. I bought ArmA some time before new years and started playing with the editor and researching stuff a couple weeks later. By the end of the month, I had both syntaxes down, and a few common commands memorized. I still use it regularly.

if i can do it in 2-3 weeks, you can, too.

and regarding the question thing... the talk pages are for questions regarding layout or clarification, or adding imfo you just figured out. Check here to for a better clarification of questions on teh Biki.

<span style='font-size:11pt;line-height:100%'>Otherwise, THIS is where you ask questions!</span>

[W0lle 1052]

I too find the Biki pretty useful, especially when I look for a command which I don't use every day.

Sure sometimes the explanations or examples could be more detailed but most stuff you find out with the examples and a little trial and error.

If there are still questions there are forums like this where you can ask your questions and friendly people (usually) are glad to help.

[UNN 0]

The wiki works ok for me as a reference. The Answer Me tag has also work well in the past, when it comes to clarifying info before it's posted on the wiki. As pyro05x says, link to a forum topics for anything else.

I do think the wiki should be the first port of call for anyone trying to learn scripting. But I would like to see a more tiered approach. Where you can add more advanced or specific info, without bogging a new scripter down with pointless detail.

[sbsmac 0]

Lots of good replies - thank you Before I respond to them I'll just give a bit of background since some of them seem to have missed the point (or more likely I didn't explain myself well). I'm a professional programmer and have no problem with sqf script. I'm not complaining about the lack of information - I'm explaining why I don't feel terribly inclined to add information that I have that isn't already present. I also work for a largish organisation where I introduced both a Wiki and newsgroups to promote information sharing so I have a reasonable idea of how they can work.

Quote[/b] ]1. The format is appropriate for a wiki, and there's nothing wrong with the descriptions. You can't expect a paragraph long description for EVERY command, and you can only really go into such detail with very few of them. Also, that's why there are notes.

Type 'strcpy' into google and follow the first 10 links. You'll see that the rest of the world has settled on a fairly consistent format for presentation of reference information. I don't see how the fact that this is a wiki has much bearing. I recall a comment from Suma where he also questioned the format.

Quote[/b] ]he purpose of the notes is for people to add discovered facts that aren't included in the description when they find them.

Yes, that's a fair point. As I say though it does have the possibly unintended consequence of implying that the policy is to always add information to the notes section rather than improving the description.

Quote[/b] ]If you're not an expert on the commands you shouldn't be editing the pages, and especially not something as drastic as merging two pages

I assume you are referring to the Wiki markup language rather than scripting commands ? Unfortunately your comment just reinforces the point that fewer people will contribute than could do. BTW, I'm not arguing against some formatting, just pointing out that the templates used are rather over-the-top. They remind me a bit of the excessive use of macros by beginner C programmers

Quote[/b] ]You read it wrong, it says don't ask questions in the notes.

True, but I've hung around the Biki enough to see that the 'DO NOT ASK QUESTIONS' is rigidly enforced throughout.

Quote[/b] ]I think you have the wrong idea about the wiki

And what makes your idea any better than mine ? As I say, I'm very familiar with the concept. I also recall Marek's recent post over in the 'whining' thread in Arma:General where he stated that the intention was to allow the community to build the documentation because BIS did not have the resource. I'm just pointing out that in order for that to happen, some information needs to come from BIS or other users and that information may have to be actively solicited sometimes. I'm NOT arguing for the ability to turn each page to the equivalent of 'why does this command not work in my script?'. However, recording some questions or areas of uncertainty does allow those of us who are prepared to go away and experiment to find answers.

Quote[/b] ]If you can't find information the best thing to do is ask on the forums, where you're sure to at least get some response, and it's likely to be the answer you're looking for.

I'm not talking about 'easy' information. When I was researching FSM's I probably knew more about the subject than any other ArmA user but there were still things that I couldn't answer.

Quote[/b] ]The Answer Me tag has also work well in the past, when it comes to clarifying info before it's posted on the wik

I'm the one who introduced the AnswerMe tag and I would not agree that it has worked particularly well. At time of writing there are only about 4 of these tags in use - not terribly encouraging for a resource which is supposed to be built by contributions from the community. It's far easier to add content by answering questions than by hoping for unsolicited contributions.

[mattxr 9]

i cant find my way around the biki sometimes and search for cetain things and always end up at a dead end, we need a command ref.. instead something i can download.

[raedor 8]

Quote[/b] ]You read it wrong, it says don't ask questions in the notes.

True, but I've hung around the Biki enough to see that the 'DO NOT ASK QUESTIONS' is rigidly enforced throughout.

Well there are different types of questions: We had many question "where is the d/l link to tool x/y" or "when gets x/y released" or other stuff that clearly is not wanted in the biki. Other questions, eg how a certain command works exactly, have never been forbidden afair.

[EricM 0]

The way I see it, the Wiki is a reference source for people who already know how to script.

It's quite a daunting tool for beginners like me because it's not structured as a learning tool (see Mr Murray's editing guide), guiding you step by step through the interface, the syntax, the commands etc... and practical "how to" examples.

(Note that, given that I have a sprocket download version, I don't even have the slightest trace of manual either.)

It's like giving a dictionnary to someone and say : learn that langage... I learned French, English, Spanish and some German. Starting with @a! in the dictionnay is not the one best way to do it... Simple examples and basic grammar first !

I have notions of basic and pascal programming language (don't laugh !, and the first thing I was taught was how to structure the program and then do simple step by step examples (Hello, my name is input$, !!.

In the Wiki, first thing you find (slight caricature) when you try to learn how to edit is something like that :

Name : Camcreatecommitpreparedarraygetpos

Function : Allow to Camcreatecommitpreparedarraygetpos a unit relative to the world axis.

Example : Camcreatecommitpreparedarraygetpos[cos _select 0 , sin _this globalvariable] execVM [init.sqf]

Multiplayer : unknown

Note : Don't forget to put {42} in you description.ext

No comment on the usefulness of this when all you want for a starter is : what is the init field for ? where do I put the mission or script I downloaded ? How do I tell X to go into a chopper ? how do I tell if the man is dead ? What is this marker/waypoint meant to do ?

[raedor 8]

For beginners, we need some pages containing a scripting tutorial or howto, no need to change the comref for that

[Planck 1]

I agree it is a command reference not a tutorial on how to script.

If you want to find out about a certain command or group of commands then the command reference is where to go.

Some commands lack a description and in the fullness of time I'm sure most of them will eventually have one. You cannot provide information that you don't have.

On another note, I was never very happy with the template that was applied, but, I live with it.

Planck

[UNN 0]

Quote[/b] ]I'm the one who introduced the AnswerMe tag and I would not agree that it has worked particularly well.  At time of writing there are only about 4 of these tags in use - not terribly encouraging for a resource which is supposed to be built by contributions from the community.

According to the instructions on the wiki, once answered the tag should be removed. Which makes sense, if we want others to wade through them all. So the lack of Answer me tags can also be an indication of how well they work to

[EricM 0]

Ok, since this is a community effort, I'm willing to make 50% of the work already.

I'll ask "how to..." and then the rest of you can JUST fill the answer...

(joking, off course)

[deanosbeano 0]

the problem is not the layout it is the info contained within.

just like you cant port an ofp addon straight to arma , nor can you

in all of the cases port virtual reality engine scripting to virtual reality 2 engine.

the new command for arma section is great but where the thing falls down is when ofp scripting code is overlapping the arma scripting code in the Arma scripting section, there has been a mass

copy and paste job there and it cause me hell with ctds and missing } ," ;" errors.

the good out ways the bad but still ,the format is excellent its the actual info thats the prob.( altho getting better i hasten to add).

[kronzky 5]

Keep in mind that the Wiki is supposed to be a community effort!

It is not meant as a top-down information stream.

Yes, there are contributions directly by BI and the beta-testers, but the reason why it was set up as a Wiki was so that everybody who has something interesting to contribute, can do so.

So, if you're scripting along, and you "discover" something new, or just come across something that is not quite obvious, just make a quick trip to the Wiki, and post your note there.

Don't worry about the format so much (even if you screw it up, somebody else will come along and fix it later), but if you have something interesting to submit don't hesitate to do so!

The contributors are still the same dozen or so people that have probably created 90% of the Wiki's content so far, but I'm sure MOST of you will have some interesting tidbits to share. PLEASE DO SO!!!

It doesn't have to be on super-sophisticated subjects, either.

Once ArmA comes out world-wide there will be lots of people for whom EVERYTHING will be new. Write something for them! Think back about the things that confused you when you first got OFP, and what kind of help and documentation you would've liked to have when you started out (for example, there still isn't even a good introduction into waypoints on the Wiki). I'm sure anybody here would be able to write up something interesting. I just don't know why there aren't more people actually doing it.

And again - DON'T WORRY ABOUT THE FORMAT!

If you don't know how to create a new page, or have problems with specific features/formatting issues, ask one of the sysops there. They will be happy to help you. They'll set up a test page for you to experiment with, and they'll even fix any formatting problems you might run into.

And another thing to keep in mind: If you're planning on using (or working on) the Web you WILL run into Wikis sooner or later. Yes, there IS a learning curve involved with using Wikis, but since you'll have to learn it at some point anyway you may as well do it with a subject you care about, and are interested in!

[whisper 0]

I can vouch for that.

I didn't participate much to the Biki, but it really didn't take long, and the format is not much of a problem : There's Kronzky coming back after you to check

[fubarno1 0]

I would really like to see a "How To" section on the Wiki or even in this forum, probably easier having it on the wiki then they can be categorised to Infantry/Vehicle/Object Commands but specific to ArmA.

I suggested it in another post i made.

Quote[/b] ]Suma said about documentation

Quote[/b] ]"but we really do expect community will help us creating it, as this is really beyond the scope of standard entertainment product. I hope the fact we are running Wiki documentation and actively contributing to it, shows we care about the users who want to customize the game and develop for it, and also shows some progress has been made from the OFP times."

I would also have to say that it is beyond the scope of the community if they don't know the answer and there is nothing forthcoming from BIS, there are lots of posts in the Editing forum that the community has not been able to answer, all it would take is someone from BIS to brows through those posts and answer those questions that have been there a few days or weeks in the case of some. Communication works both ways, the community wants to help make ArmA as much as a success as OFP/Res was but without the tools or active involvement from someone from within BIS offering guidance/answers where they are needed then ArmA could be heading down the slippery path of "it had potential but never quite made it".

I know nothing about modding or scripting and rely on the more intelligent members of the community that do to for-fill my wants and needs, I am also sure that I am not the only person that needs to look to the community for inspiration and if BIS are going to try and bring new blood into the realms of their vision for a realistic battlefield experience then they have got to address the need for good editor documentation even if its built up from a combination of BIS/Community input, the wiki may work for those that have the skills to understand what is put up there, but for the average Joe Bloggs who wants to make his own mission in the editor visiting the wiki can be a daunting task especially where items from OFP are listed in the ArmA section that don't work or are not implemented in the engine yet. The wiki is designed to help those that already know their way around mission editing, but there is nothing there that will help slowly guide a new player in to the realms of mission editing, whats needed is a "how do I section" that explains in layman terms how to make something happen example:

Quote[/b] ]How do I get units to mount a vehicle?

Answer:

You can instruct a player or a group to mount most vehicles (if the mountable spaces are available).

to instantly spawn in the locations you use the "movein" command.

Player: this moveincargo carname

Group: {_x moveincargo carname} forEach units this

locations are

Commander: this moveincommander vehicle

Driver/pilot: this moveindriver vehicle

Gunner: this moveingunner vehicle

Cargo: this moveincargo vehicle

to mount via a get in waypoint use "assignas" command, they will then mount the vehicle as instructed.

Commander: this assignascommander vehicle

Driver/Pilot: this assignasdriver vehicle

Gunner: this assignasgunner vehicle

Cargo: this assignascargo vehicle

to mount in a turret

1st gunner: this MoveInTurret [yourVehicle,[0]]

2nd Gunner: this MoveInTurret [yourVehicle,[1]]

I know we had a how to in the OFP forum that helped new players a lot, we need something similar dedicated to the ArmA section (even though most commands do replicate themselves between engines) as there are going to be quite a few players that have never heard of OFP/Res so why confuse them by sending them to an older engine, the easier it is for new players to find their footing the more likely they will recommend ArmA to others.

If BIS are looking to the community to get word out about ArmA to new players, then they also need to take a leading role in making this forum & wiki more helpful and inviting to new players.

Having somewhere that new community members (and those clueless in mission making wannabees (self included)) can visit to find answers to the most common editor questions without having to search through loads of other posts that may not have a direct reference to what they are looking for would be a major benefit to both them and the forum (same questions being asked time and time again).

the OFP "how too" thread was good, but again it was a matter of searching quite a long thread unless your search criteria was very specific and can be quite frustrating, do a search in the mission editing and scripting forum for "mount a vehicle" and it comes back with 3 pages 80% of those listed have very little help in answering the question asked.

This forum or wiki needs a more user friendly way that mission makers can find answers to their questions without needing to be a scripting expert.

[sbsmac 0]

Quote[/b] ]

So, if you're scripting along, and you "discover" something new, or just come across something that is not quite obvious, just make a quick trip to the Wiki, and post your note there.

...

I'm sure anybody here would be able to write up something interesting. I just don't know why there aren't more people actually doing it.

Thanks again to all for an interesting and intelligent discussion.

Kronzky, I was trying to provide at least some answers to your question with my post. Obviously others may have different reasons for not contributing more.

From my own perspective, format is an relatively minor annoyance compared to the rigid 'no questions' policy. For myself, and I suspect many people, it's much easier to improve existing documentation in response to an outstanding question than it is to try and figure out whether the random collection of knowledge in my head might be useful to someone else and to then format it in a coherent manner. Ideally, questions would be asked only on the forums but I think the 'round-trip' delay introduced by this mechanism crosses the effort threshold for most people. Please understand I'm not arguing to turn every Biki page into a discussion forum but allowing a lightly-moderated 'to be answered' section for a page might help solicit more information.

*Edit* And Plank wrote...

Quote[/b] ]You cannot provide information that you don't have.

But you can provide information you do have. It's just that sometimes 1) you may not even realise you have it until 2) you may not realise that some other people _don't_ have it

[crashdome 3]

I agree somewhat.

Hardly anyone who has the knowledge bothers with the wiki and you cannot make them. And if they do, how do they know where to start? If there were questions like with the "Answer Me" template then someone who has the knowledge can see specific problems.

Think of it like seeding...

One thing I have a problem with the wiki is the almost god-like presence of a minority of users. And I don't mean they are intentionally ruining everything, but IMO unless content is offensive or illegal, etc... it should be let alone for awhile and chipped away at rather than restructured constantly.

Also, in regards to the commands... can we get another XML version of the data? Like one page will dump XML output?

Searching includes the whole wiki and trying to externalize the command list is next to impossible. For example, if someone needed to make a quick reference, they would be cutting/pasting for hours to get a good printout.

[hoz 0]

First let me say I like the format of the templates, although it was a bit overdone(too many templates) but that said you get a nice presentation to what was a dull com ref. In reality when you look at the full listing of commands its no different then the old BI comref. All the commands are there in alphabetical order. With the help of many people the see also sections are being populated which also helps you see related commands. I agree the search is not the best but I'm not sure how you improve that and with the 800 or so commands its difficult to make any changes.(I know I've changed all 800+ commands several times )

Quote[/b] ]From my own perspective, format is an relatively minor annoyance compared to the rigid 'no questions' policy.

Perhaps we can loosen this rule abit. When the wiki was built we had no idea how many questions would be ask, the nature of the questions, etc. Rather then being overwhelmed we took the more cautious approach when there is a forum which is more suited for discussions and more people can answer the questions.

Quote[/b] ]Having somewhere that new community members (and those clueless in mission making wannabees (self included)) can visit to find answers to the most common editor questions without having to search through loads of other posts that may not have a direct reference to what they are looking for would be a major benefit to both them and the forum (same questions being asked time and time again).

Then perhaps start a ArmA - Editing FAQ page. Just like I did for ArmA FAQ and ArmA Troubleshooting so that newbies have some place to start.

Quote[/b] ]

Also, in regards to the commands... can we get another XML version of the data? Like one page will dump XML output?

I'm not sure if BI will do that this time around, the last couple of comref's I received were not complete, lots of typo's, some mistakes here and there that have been corrected on the wiki. Now that might of changed and perhaps they have someone working full time on documentation, but I doubt it. The comref can be exported to xml and then perhaps processed some other way, Gaia did this for a cz wiki.

If you have any ideas on how to make the Biki better then lets hear it.

[Romolus 0]

sbsmac, thanks for raising those issues and I completely agree with you!

This wiki should be from community members for community members, but how can that work when it's so damn hard to add content? I already mentioned that in a talk page in the wiki, but there doesn't seem to be any place for a healthy discussion there.

The point of having questions in the wiki is not that everyone and his grandmother can ask what socks to wear, but to show what kind of info is needed. I bet most of us don't have the time putting together a well thought through article for the wiki or go through all the commands and add everything we know and might be of any help.

When the AnswerMe tag was introduced I thought that it was the right way to provide exactly that: An easy way of finding out where you can add something to the wiki that does actually help someone and add content to the wiki at the same time. But the tag was never used at all.

Same for the other points that sbsmac is raising. Those make it harder to contribute to the wiki.

It's already hard enough and time consuming to do the research for OFP and Arma so why even bother with adding those findings to the wiki if it's cumbersome to do so?

How is someone supposed to see where spending a bit of time can improve the quality of the wiki without spending a whole weekend to go through the whole thing?

If it's way harder to put info into the wiki than to get it out, no wonder it's not going anywhere.

The whole point of a wiki is to make it easier for anyone to contribute. So why not make that the top priority instead of having endless revisions to templates and all kinds of things that are only related to getting info out of the wiki but not into it?

Make it easier to contribute and there'll probably be much more people who do so.

[UNN 0]

Quote[/b] ]When the AnswerMe tag was introduced I thought that it was the right way to provide exactly that: An easy way of finding out where you can add something to the wiki that does actually help someone and add content to the wiki at the same time. But the tag was never used at all.

I've used it once, it was promptly answered. I deleted it and added the content to the wiki, based on the reply I got. So it worked for me.

Perhaps half the problem is complacency, I find most of the content added for commands (params e.t.c) quite straightforward. Others don't and sometimes ask questions on the forums that some people can easily answer, just by looking at the wiki. But if you understand it, then why would you think to update it?

Thanks to the people that spent the time adding parameter details, the whole conversion to Arma has been far less painfull  

[kronzky 5]

I understand the frustration with the command definition template (I find it quite frustrating myself). And perhaps we can find a way of making it more user-friendly.

But that's really the only part of the Wiki that's template based. The rest of it is pretty-much "free-form", and it's totally up to the submitter to decide how it should look like.

There is still the Wiki syntax to familiarize yourself with, of course. But it's not any harder to learn than forum or HTML markup commands, and, as I said before, it is a universal skill that will probably come in handy at other opportunities as well, so the time spent learning it is a fairly good investment if you spend a lot of time on the web.

[fubarno1 0]

Then perhaps start a ArmA - Editing FAQ  page.  Just like I did for ArmA FAQ and ArmA Troubleshooting so that newbies have some place to start.

Yea right, If I knew how I would

Never seen a wiki or been interested in one until I have been forced to look at the one here, but knowing my luck I'll probably break the damn thing.