improving FIBS documentation

[alef]

Not sure where to post this, but didn't want it just lost in the Chit Chat section so have started a new thread here.

klic  Posted: Mar 24 2004, 10:25 AM
Yes. I think the most important thing here is that newbies aren't just treated bad so they log off and never return...

It might not make an enormous difference but one of the things we can easily change is the website material written for newbies. Please constructively criticize and suggest changes:
http://www.fibs.com/guide.html

Also, work was started on a large FAQ some time ago. It borrows heavily from www.dailygammon.com and needs lots of rewriting and links. If anyone would like to pick this up and develop it, please do! Or even just work on part of it?
http://homepage.mac.com/alefrosenbaum/fibs...jects/help.html

thread continued from...
http://www.fibsboard.com/index.php?showtop...st=40&#entry953

[klic]

That would be a good start. I know, there will always be somebody who does not read the FAQ but just starts shouting, asking for help, but with a good FAQ this might then become quite rare...
If nobody else already started it then I would volunteer to at least polish the (large) FAQ a bit. It's not my first FAQ I would work over, and I'm probably still "newbie enough" to know what problems might need an (easy to find) answer.
So, if nobody started it and there are no objections, I'd start it...

Klaus

[alef]

klic, it would be great to have your help with this! Looking at it again, there's already a lot done -- file attached.

This was originally copied from DailyGammon and then GregS spent some time adapting it to FIBS and I put in some of the links. There was generally a loss of enthusiasm in late 2002 when Andreas (FIBS creator) didn't answer our letter (see http://www.fibsboard.com/archive ). But there is now a new burst of energy following TourneyBot and the relaunch of this board so it seems a good time to kick this FAQ together!

When done it can be at www.fibs.com/help.html so links can be written in relative to there.

Feel free to take this file and run with it, or just pick some areas to check through and sort out. And this forum is a great place to post questions about it. For example I don't know what to write about the dice, although I assume both the FIBS server documentation and rec.games.backgammon archive contain explainations of how exactly FIBS dice are generated.

Maybe our first aim is just having a basic FAQ we can put on the site soon and then later build it up to be as all inclusive as we can make it.

[klic]

Ok, then I'm going to first just work over it, get the links done and stuff, and then fill in the missing documentation. I guess I will have to ask some stuff, but then there's also quite some heap of information out there. We'll see!

Klaus

[klic]

Ok, I did the first pass over the FAQ, just getting links done and polishing a few entries, especially those which were still open. The only point I did not work on up to now is the question about who are the friendly fibsters who are helping newbies
Please everybody have a look at it, as I'm no native speaker.

And, of course, any comments and extensions are definitely welcome! (in this thread or as private message)

First shot at the FIBS FAQ

Klaus

[alef]

Excellent, great to have this developing again! Because this was started a while ago some things are out of date. Things I've immediately noticed at the top:

- help for 3d, Java, Real should now point to the relevant Board forums
- RealFibs needs adding
- refer to FIBS as a 'server' not a 'site'
- let me try writing a new basic connecting to FIBS... (see below)
- the 'helpers' idea hasn't ever/yet come together, just direct them to this Board I guess. does using the 'shouts' work?

OK, have to stop for now, have to take this FAQ in small chunks at a time I find.

Alef

-----------

How do I connect to FIBS?
There are three different types of connections. <a href="">Browser based</a> interfaces work directly on the web (using Internet Explorer, Netscape, etc), <a href="">download</a> interfaces are the most popular and there are various available, or you can direct connect with <a href="">telnet</a> without an interface (recommended only for those already familiar with using command lines).

What's a browser based interface?
These don't require any downloading and can work directly on the web. <a href="">JavaFIBS applet</a> works with most browsers that aren't ancient or, more specifically, with any browser that fully supports Java 1.1.5 (but unfortunately doesn't currently work on Apple Macs). Prior to using JavaFIBS applet you must already have an account with the FIBS server which you can create <a href="">here</a>. <a href="">ParlorPlay</a> is another browser based interface and it works on all platforms. You need to register with both ParlorPlay and the FIBS server.

What are the FIBS download interfaces?
The three most popular and still supported for Windows are  <a href="">3dFiBs</a>,  <a href="">JavaFIBS</a> and <a href="">RealFibs</a>.  Apple Mac users have a choice between  <a href="">MacFIBS</a> for OS 7-9 and  <a href="">JavaFIBS</a> for OS X. On the <a href="">connecting to FIBS</a> page you'll find a full list of Windows clients plus others for Unix, Linux, cell phones and palm tops.

What are FIBS commands?
All interfaces use them and you can enter them yourself, look for either the command or terminal window. These <A HREF="CommandReference/index.html">commands</A> are useful to all Fibsters and essential to telnet users. For example, do you know about <I>waitfor</I> or <I>whisper</I>?

[klic]

Ok, thanks for the input, I tried to add it to the FAQ. I'm a bit "time challenged" right now, so I did not really cross check it right now, but I hope it's fine so far. I also tried a first shot at the helpers entry.

FIBS FAQ preview/development page

[alef]

The only time deadlines would be ones we create for ourselves, and this FAQ is too big to rush! I'll be updating the site for April in the next few days, but would rather wait a bit on including the FAQ since I'll have more time to go through it next week during my Easter break.

Do you think we need both http://www.fibs.com/guide.html and the FAQ? I'm tempted to merge the guide into the new FAQ and just have the one page.

[webrunner]

The question is.. do we really need a big FAQ?

I think it's better to have a small howto and let this forum be the FAQ.
In fact.. we already have a topic for it here.

[alef]

webrunner, your basic steps of how to connect using javafibs are excellent, definitely like to include that into the FAQ. isn't it easier for people to read one page which is a tidy organized page rather than from lots of questions posted on this forum? certainly plan to direct people here for an additional help, but I would like to have one fairly comprehensive guide available at www.fibs.com.

though maybe i'm wrong, i'm not a newbie -- what do others think?

A -- Long FAQ full of info, or
B -- Short FAQ then just link to forum?

[klic]

Judging from my experience with FAQs I think they are quite valuable as they condense the information in one small place. THis is not to say the FAQ does have to be that long. We probably could condense some answers and point to fibsboard, but in my oppinion it is often easier to find the information (at least basic answers) in one place (the FAQ) with more explanations and/or background information pointing to the board.

So, yes, we probably should condense the guide and the FAQ, and probably shorten a bit, but I think the FAQ is quite valuable for beginners.

Klaus

[diane]

I know i am the dinosaur here - but i am STILL having trouble finding stuff here!  I think tidily, in one place is a good idea for people getting started - and as you say - point here.

[klic]

Still tuning and looking.  

Some questions:

is this (still) true:

There is a match length limit of ?? pts imposed on new users until their experience rating reaches ? points

Well, how are the dice generated? Guess some "standard" prng?

I bet my wording in "Are there any tournaments played on FIBS?" is wrong. It just feels wrong But as I said before, I'm no native speaker...

So much for now,

Klaus

[jinnate]

i definitely vote for long faq chock full of well-organized information in a structured format. i, as a newbie, do not want to go hopping all around the web, unearthing answers. also, fibsboard takes a moment to load on my computer, and when i imagine a newbie looking for answers, i would submit they want a quick, easy solution to finding them. pointing to fibsboard for additonal information, yes. but i would say, as much as possible, answer newbie questions in the faq itself.

2nd 2 cents. definitely keep the guide and the faq. guide is for perusing at my leisure. faq is for specific questions regarding stuff. different structure for different mindframes. i'd vote against combining them or tryiing to do away with one or the other.

i was going to recommend a section on bots, especially tourney and repbot, but i haven't thoroughly checked out their faqs yet. i would offer that it might be better to cover some basics about both in the faq, primarily so newbies don't have to keep digging for answers. the less confused a newbie is, the easier life is for all of us.

[jinnate]

i'd like to suggest a direct link from the faq to the fibs hall of shame page http://www.fibs.com/savedgames/shame.html .

[don]

The fact is, FIBS has very adequate documentation, thanks to marvin, for what it is: A telnet server.  Most who whine, whine because whatever-interface they are using does not provide a connect to the easilly-accessable (for any GUI) good FIBS documentation.

Here's a suggestion to GUI/FIBS writers.

Help while NOT reinventing the prefectly good wheel

...try sending most INFO requests to the very good FIBS help files
......(easy to parse)
...then try something specific to your GUI

...(also,

......while
.........a creator of TourneyBot
......try to stucture your help files AND program
...)

wend/Help

[klic]

This is very easy for people who are computer savvy. Many people aren't just this. They use the machine for surfing and, in our case, using it for connecting to FIBS in one way or the other. They do not know how to find their way around or use that tool efficiently. Heck, there are lots of drivers who don't know anything about cars. So what? Not everybody needs to take computer science courses to find their way around. So yes, many here know how to help themselves if there's a problem, but for everybody who knows where to find the documentation there are 10s (well, would be good if the number were that low...) of people who don't. I don't see a problem to try to create a documentation that tries to list everything in one place, it's just easier for people to read, and even I enjoy reading FAQs from time to time because I tend to forget things and always find something interesting in there
And if there's something like a FAQ or a centralized document that directs those people where to find anything without asking people on FIBS, upsetting the short tempered crowd, the better.

my 2 euro-cents

Klaus

[don]

You are exactly correct, klic!  It should not be your problem, interfacing with whatever, it should be easy.  Anything else is a sloppy user interface!

[socksey]

is this (still) true:
QUOTE  
There is a match length limit of ?? pts imposed on new users until their experience rating reaches ? points


I'm not sure what the match length limit is for newbies, but I know there is one.  You will most probably get an error message if you try playing a longer match as a newbie.  The experience magic number for shouting used to be 100.  This may be the same for match length, although I have seen newbies shout, so am not sure about this.  Perhaps the shouting is only limited before 100 experience.  LOL  I'm lots of help!  ))

socksey



"If I only had a little humility, I'd be perfect." - Ted Turner