Frustrations with Biki

[hoz 0]

Quote[/b] ]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?

When was the last time the command template was changed? Like 5 or 6 months ago if I recall.

Quote[/b] ]

This wiki should be from community members for community members, but how can that work when it's so damn hard to add content?

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

So far the entire content of the wiki has come from the community. With some updates/corrections made by BI.

How hard is it to click edit, add some text, and click save?

[baddo 0]

We definitely need a local copy of the comref in XML form. An up-to-date comref like the one Hoz is talking about is enough. Justifications: People can use it on computers not connected to Internet. People can use it to read the information relatively easily into a program and process as needed. It is much more convenient to use as a reference by people (who already know how to script) than the Biki is, because there is the command reference and nothing else. Some people have ISP's which are not reliable. Some people use slow modems. Not all people have internet connection. Etc. the list goes on and on. And last but not least, I've said this before and I say it again: documentation directly needed in the in-game mission editor should be shipped with the game and it is a shame that it has not been realized by BIS. Documentation is an important part of the in-game mission editor and as such should not be left out from the game package. You don't require an internet connection to be able to play the game; why do you require it for getting documentation for the in-game mission editor? This is not about addon creation, this is about documentation for something which is directly accessible through the in-game menus. If you disagree, take the mission editor away from your products because without documentation it is not far from useless.

To the Biki issues, then.

You could provide downloadable snapshots of the whole Biki. That is done by some people already somewhere else and I think it is very good service, I use such a local copy just because it is faster to use. I'm sure this does not require much from BIS to automate, like, say one snapshot a month.

Another thing about the Biki. I see it as a problem if I go to the Biki, navigate to OFP command reference, look at a command and what do I get on the page? I get links to commands which only work in ArmA! Now isn't that nice, just what I wanted to see! Not... That's a problem I am telling you. It is all over the place. True, true, many commands are equal in both games, but this really doesn't help new people who try to figure out how stuff works I am sure about that.

In general, the Biki is an interesting concept and probably it will become great over time. What is keeping me from adding content into it or fixing it (other than the very small fixes I've done this far)? It's almost all been said in this thread already. One more thing which is keeping me from contributing: I am 100 % sure that after writing an article containing as precise and correct information that I have been able to gather during the many years of OFP exploring and experimenting, someone will come and break it. That is not a question of if, it is a question of when. That is a major reason for me to not start contributing into the Biki. I'm quite sure many other people have the same feeling too, they rather put their text where they have total control over it. If that's no place at all, then it is a shame. Maybe more restrictive editing of the Biki can make this problem go away.

Thanks for reading,

Baddo.

[crashdome 3]

In their defense, Baddo, if they are having a problem getting people to update, then they are very unlikely to have alot of people breaking stuff. However, I do somewhat agree in that there is/was too much re-editing, but mostly by a few that IMO are/were overly-excited to polish everything the minute it is posted. I speak in both tenses because honestly I haven't looked at the wiki other than a few commands in the past month or so.

In regards to the XML, I am looking into parsing the HTML pages to extract the information. It's a double-edged sword... a wiki... you can easily edit, but it is NOT a good source to store data. Atleast not the way they work now. The web is moving towards seperating content from form and the wiki's only answer right now are templates and even then it is half-baked. It only works on the initial page creation.

Ugh.. back to topic... IMO online documentation is not that bad. If you got here, you can get there. Having a way to present it in multiple forms (i.e. print out) is the real question and wikis cannot do that yet. As I said, I MAY look into parsing the HTML to extract the commands into XML with a few reg expressions, but I am not promising anything. I have too much going on. The obvious drawback is when things change, but if you can do it once... you can repeat the process every few months or so.

[kronzky 5]

MediaWiki (the software that's used for the Biki) already has a built-in function for exporting XML data.

Just go to Special Pages|Export Pages and enter the titles of the pages you want (one per line), and you will end up with a nice, big XML file.

If the exported page used templates those labels will still be in the exported data, so your parsing software would have to interpret them somehow.

[fasad 1]

A good source of beginner grade tutorials and how to's could be the OFPEC tutorial page. Unfortunately some tutorials contain strict copyrights.

[pyro05x 0]

in order for someone completely clueless to the subject of scripting and editing...the first place to start is to simply go out there and play some high-quality missions. put some objects down in the editor...this is where you figure out rotation, ranks, and object types.

next, load up a mission template. look at the components and the way it's set up. there's not a whole lot of code in the mission editor, but it's where the content is. you should get the gist of things eventually. load up some of the files into notepad or your preferred text editor.

while doing this, learn the syntax. most of the commands used are pretty self-explanatory, but for one you don't understand, look it up on the list. after a couple days, i figured out the basic structure of a mission...or so i thought...

take a peek at mission design. this information is priceless because it tells us about so many different things! after that you should be able to take it from there. you will get better and better every day you study this stuff. heck...i still am getting better...smarter...faster...and getting less sleep.

it's sort of a thing where you look at all these biki pages at once (thanks to firefox! tabbed browsing pwns).

i remember when i had notepad, arma mission editor, and like 3 different biki pages open at once....it was a day to day thing.

you have to want to learn it to learn it. if you're not getting it, you're not trying hard enough, because you don't want it enough.

oh...and in case anyone in interested....i've got syntax highlighting keyword files for SciTE as well as Notepad++. i'll post them somewhere this week.

EDIT: they are for file types SQF files and i have another for SQM and EXT.

[baddo 0]

CrashDome, there exists a comref for ArmA which is similar to the official comref 1.85 for OFP as hoz hinted about it, saying that the latest version he received was not up-to-date. That comref is much more suitable for reading with a tool as it is in good XML format, as you probably knowalready. Notice that before you spend a good amount of time writing something to parse the Biki if you do it only to get the command reference. Maybe BIS will listen to us and release an updated version of that comref, would save us a great deal of pain.

pyro05x, I recommend starting a new thread here when you release your syntax highlighting rules, so you get good visibility for them. Thanks in advance for releasing them.

Baddo

[Romolus 0]

Could we please stay on topic of what sbsmac posted in the first place?

You all post interesting comments but I find that it's hardly addressing the points that sbsmac made.

He said he's familiar with how a wiki works and knows how to edit the content there. He also said that he doesn't have problems with OFP/ArmA scripting.

What he said is that pretty much every command reference is structured different to the OFP/ArmA wiki and that it works very well that way for all sorts of programming languages and I have to agree with him there.

The next point he's raising is that he's doing his own research for OFP/ArmA scripting (which means he's not a newbie who has a hard time getting the basics from the wiki!) and that he finds it pretty hard to contribute his findings to the wiki because of the templates, the notes and the fact that there's no real way to tell what other people would like to know because no one's really using the AnswerMe template, nor are there other means to find out where people would like to have some more info than what's already there in the wiki.

And I have to say that I find myself in the same boat.

I also find it easier to answer questions on topics that I did some research on and by doing that contributing to the wiki. But since no one is using the AnswerMe tag, the only way to find out what's going on in the wiki is the recent change page. And in addition posting questions on the wiki is even discouraged. Instead the knowledge is piling up in forum threads and is forgotten once the threads wander off the first page.

Why not encourage people to post command related questions in the wiki instead of the forum by using something like the AnswerMe tag that lists all the questions asked in the wiki on a single page that is linked in the main menu of the wiki?

That way it would be much easier to see where people are struggling and where the content of the wiki needs some improvement.

Hardly anyone will update the wiki with things he gathered from a forum thread, but if the question is asked in the wiki, the one answering could answer the question and clarify the existing content at the same time.

If you want people to contribute, then why not make it as easy as possible for them to do so? And we're not talking about getting the grips on learning the wiki syntax. It's about making it visible where additions and clarifications to the existing content are needed and that's something that's pretty hard right now.

Once the contribution part works well, it makes sense to see how the content can be made more accessible, but not the other way round. Otherwise you have a pretty shiny com ref that doesn't have much use because no one's really contributing. And that's how I find it is right now.

[crashdome 3]

MediaWiki (the software that's used for the Biki) already has a built-in function for exporting XML data.

Just go to Special Pages|Export Pages and enter the titles of the pages you want (one per line), and you will end up with a nice, big XML file.

If the exported page used templates those labels will still be in the exported data, so your parsing software would have to interpret them somehow.

Gorgeous...

Working on the app to parse that data now. It will be alot easier working with every command in one file than several pages. It is a bit odd to take XML and transform it into... XML ... again... but this is by far going to be alot easier than any other way.

@Rom

The purpose of me getting out the XML is to alleviate the need to go to the wiki for every single command. It will not be hard to create a stand-alone command list (with links to the original page on the wiki of course). It may only be partially related to sbsmac's original request, but it is related as I am in the same boat as you two also. I just think one of the best ways to get the commands into my hands during an editing session is with pre-formatted text which I can print or use otherwise. I guess I am just approaching from a different angle is all.

[bedges 0]

Quote[/b] ](for example, there still isn't even a good introduction into waypoints on the Wiki)

ahem...

since the biki has been constructed in the main by community members, with all due respect to those involved the priority seems to have been getting the information in there for the existing community. very little of the content is written at a level easy to understand by those new to the games, and even the stuff that is created with the noob in mind is difficult to find - the above topic being a perfect example. the biki's navigation is not intuitive, i must admit.

regarding my own issues with the scripting area layout template, it's sometimes a lot of template for very little actual content. for example, the nice blue titlebar says "Description", then underneath is the sub-title "Description:"... same with "Syntax"... when looking for information, even as a seasoned editor i find it difficult to get at what i need amongst the seemingly redundant bits of layout.

that said, again it must be stated the biki is a community-led effort, not a professional exercise in information architecture. i think so long as the community continues to express its varying needs, and there continue to be enterprising and like-minded folk to fulfil those needs through a variety of outlets (Biki, BI Forums, OFPEC, etc.) we should be okay, noobs and veterans alike.

[UNN 0]

Edit:

Forget it.

I look to the Wiki as a reference rather than a tutorial. So my comments are not realy valid.

[.kju 3244]

Whats the worst things to happen to a good discussion?

No change. No effect.

---

I think one key element here that no one really feels responsible for the BIKI. BI handed over to the community and its stuck now.

There are the sysobs and they've done a great job - still you can see that they don't feel like its their baby and are busy with other things.

Forge a BIKI-usergroup / team - recruit people for that.

From the people doing comments here you have a good idea where to start.

The vision of this group is to push the BIKI forward and actively tackle tasks and topics related to it.

It doesn't imply that they are doing all the work. More the opposite - they are working on the framework and all things besides the content (- they can contribute to the content too of course).

Or define your own vision, concrete goals and the strategies to achieve them.

In my view the BIKI should become the central place for information related to BI products - no just an enhanced command reference.

Concentrate all knowledge in this platform for every type of user!

Possible topics for the agenda:

~ Media campaign - get the BIKI much better known (news site - cooperations) - get the word out

~ Ask also common people directly (via different sites?) what there specific problems are when using the BIKI or trying to contribute

~ Get away from the professional level and try to concentrate on beginners as well - without successors the community is predestinated to the doom. The goal has to be to make it easy as possible and least time consuming for beginners to learn!

~ How to achieve easy contribution shown by different concepts in the BIKI (question-answer contribution, stubs, answer-me tag) - you have to TELL people how this works and not just assume that people might have read this one thread or get it by themselves

~ How to promote sharing of knowledge

~ Tiered approach - entrance to beginners, advanced people and professionals

~ Setup a topic here in the BI forum for common people to ask simple either general or specific questions as a base to add content to the BIKI

~ Gather missing information which needs to be delivered by BI

~ Integrate (stubs of) tutorials for editing and modding (to encourge people fill in): like how to make a single player mission / campaign / mp mission: coop/ctf/c&h, how to create a weapon / jeep / tank / helicopter / x turret vehicle, how to setup a dedicated server, how to ease mission testing / modding

Right now the BIKI is mainly a summary of information, yet the access is very very hard to it right now. More specific guides on topics like these would definately help and they would be mainly a simple page interlinking the important BIKI pages for the current topic with some comments and overall setting

~ How to get people from modding teams share their current knowledge

~ Get people from OFPEC / Mapfact / other sites to reduce the 1on1 support and contribute more in a general approach

~ Get all the information of OFPEC's guides and tuts in the BIKI some way or another

~ Get Mr-Murray's editing guide in there

~ Get the information from this thread out to the people - most namingly Kronzky's stuff

~ Easier access / ways of making use/contributing for people with an English language barrier

Take action!

Good speed.

[crashdome 3]

Q, I love your wisdom sometimes, but to be honest this is going to be hard for me to say.

Not everyone is happy with the wiki as a central place. I know I am not. I like wikis... I like them because they are good general references and provide dynamic information.

Problems:

A) Campaigns to promote it aren't going to help. It's been promoted, people fear working on it. I think a group will form when it is easy to use and not as "structured" and complex.

B) There are times when a wiki is NOT the answer. For example, a good offline command reference - whether printable or not. I hate to bring real prog languages into scripting arguments for obvious reasons but most languages have the comments and parameters described within the code for their APIs and a good documentation engine will output the results in a good data format. Not simply as "pages" which have generic structure. I was actually surprised when BIS basically proclaimed they have no internal documentation system for their scripting language. I've dealt with so many third-party programs APIs its not funny.. and all of them have EXCELLENT documentation compared to this. BIS really needs to get with the times on alot of this.

C) I really feel alot of people from the community who were the core of the community for OFP have either left or gone to work on VBS which simply solidifies my theory that the remainder of the community is getting shafted indirectly/directly. Which means it will take time to rebuild the community again.

ah yes.. time.

I really think time will heal most of the community problems including the wiki. For one to say things in this thread are irrelevant is missing the point. I think the problem with the wiki is an extension of alot of these things.If we focus on "just the wiki" we are neglecting the overall picture.

and Q... I am working on something. I am hoping it brings the community together more and brings "change". I have "defined my own vision". If it sticks.. great.. if not, we'll move on.

@everyone looking for offline command reference:

It's on its way.... and then some. Please be patient.

[zwobot 19]

@everyone looking for offline command reference:

It's on its way.... and then some. Please be patient.

Hear, hear

[VictorFarbau 0]

I had thoughts about this, too  

1. We need compact offline documentation such as is available for every other programming language. End of story.

2. I think this is a good example of excellent engineering going to waste due to no efforts to document properly.

If Crashdome is right and even the relevant team within BIS don't have a real in-depth documentation then this is serious. Maybe they don't have such a high attrition rate yet; but once they do they will start spending more and more time on learning again what the older generation just had present from the top of their minds. The old story: while the mastermind approach is by far more compelling and a lot faster the documentation approach is more longlasting and succesful.

3. BIS has a unique scripting system and should be proud of it - at least I have never seen such a complex system of scripting and addon possibilities in any other game before. I really love it. What cracks me up is the amount of effort being put in from BIS to make this work but then present it in such a "hands off" manner (like leaving it to the community to find out how things really interact and work, add documentation etc).

3. Some really helpful documentation for beginners is only in german at this time and has turned into a commercial project. Nothing wrong with earning money for books - but it just looks awkward to me that BIS rather piggy-backs on an individual effort instead of providing this themselves.

4. I don't think the typical newbie can relate to this approach and when he ends up in these forums and vents some frustration he gets his fingers slapped by the old dogs hanging out here for years. I think it would do a lot of good if BIS would announce a new community manager ASAP who manages communication and maybe organizes meetings to set up some tools and processes that really meet the communities needs.

It's of course all easy to say and judge from the outside if you don't have inside knowledge about the schedules and (probably tight) resources available. But that's the same in each company I guess

Regards,

Victor

[kronzky 5]

Well... I would assume it's a matter of priorities and budgets.

Would you rather have BIS spend their time and money creating perfect documentation and how-to's, or would you rather have them put that effort into improving and enhancing the game instead?

And no, "both" is not an option...

And while it's true that commercial programming languages that have been around for a while will have good documentation, working on BIS games is more like participating in an open-source project. Documentation will be very erratic; most of the time it's trial-and-error, and since it's a volunteer project nobody wants to take over the boring job of documenting it.

Try participating on any open-source project (Firefox, or MediaWiki, for example) and you will really be in for a lesson in frustration...

[zwobot 19]

Documentation will be very erratic; most of the time it's trial-and-error, and since it's a volunteer project nobody wants to take over the boring job of documenting it.

Well documentation is very important in a commercial scope and if it was done properly it is much easier to learn things from scratch and apply fixes/patches/modifications.

Documenting may not be fun - especially if you have to do it afterwards but it is vital. You may be successful without decent documentation but you will save time and money in long terms with a solid documentation of your product.