Updating the F@H guides

[MtM]

Who's doing them at this time?

Xilikon made the install guides linked from the download pages, 7im maintained allot of the faq's. But Xilikon as I heard has been of the forum for some time ( sounds like me doesn't it ). And we can't expect 7im to keep all content up to date.

I was a big pusher of the guides being centralized instead of how it's been in the past when most teams made their own guides, and my thoughts on this have not changed. Centralized guides mean better guides, but only if one can both read them when in need of info and at the same time one can make additions or changes to them when needed..

The problem I see now is that the guides are again getting outdated, and the download page is also confusing. I for one wonder why 6.23 is listed as required for 5xxx cards, while the 6.32 Gpu3 client should be able to run on those cards as well without problems.

I just updated my 6.23 client (systray) with the 6.32 one ... I removed the flag, and it's working fine :

Code: Select all

# Windows GPU Systray Edition #################################################
###############################################################################

                       Folding@Home Client Version 6.30r2

                          http://folding.stanford.edu

###############################################################################
###############################################################################

Launch directory: C:\Documents and Settings\toTOW\Application Data\Folding@home-gpu
Arguments:  -verbosity 9 

[18:24:40] - Ask before connecting: No
[18:24:40] - User name: toTOW (Team 51)
[18:24:40] - User ID: 601F038459748B0C
[18:24:40] - Machine ID: 2
[18:24:40] 
[18:24:40] Gpu type=1 species=4.
[18:24:40] Loaded queue successfully.
[18:24:40] Initialization complete
[18:24:40] - Preparing to get new work unit...
[18:24:40] Cleaning up work directory
[18:24:40] + Attempting to get work packet
[18:24:40] Passkey found
[18:24:40] - Will indicate memory of 3062 MB
[18:24:40] Gpu type=1 species=4.
[18:24:40] - Detect CPU. Vendor: GenuineIntel, Family: 6, Model: 10, Stepping: 5
[18:24:40] - Connecting to assignment server
[18:24:40] Connecting to http://assign-GPU.stanford.edu:8080/
[18:24:40] - Autosending finished units... [September 12 18:24:40 UTC]
[18:24:40] Trying to send all finished work units
[18:24:40] + No unsent completed units remaining.
[18:24:40] - Autosend completed
[18:24:42] Posted data.
[18:24:42] Initial: 40AB; - Successful: assigned to (171.64.65.102).
[18:24:42] + News From Folding@Home: Welcome to Folding@Home
[18:24:42] Loaded queue successfully.
[18:24:42] Gpu type=1 species=4.
[18:24:42] Sent data
[18:24:42] Connecting to http://171.64.65.102:8080/
[18:24:43] Posted data.
[18:24:43] Initial: 0000; - Receiving payload (expected size: 99119)
[18:24:44] - Downloaded at ~96 kB/s
[18:24:44] - Averaged speed for that direction ~52 kB/s
[18:24:44] + Received work.
[18:24:44] + Closed connections
[18:24:44] 
[18:24:44] + Processing work unit
[18:24:44] Core required: FahCore_11.exe
[18:24:44] Core found.
[18:24:44] Working on queue slot 02 [September 12 18:24:44 UTC]
[18:24:44] + Working ...
[18:24:44] - Calling '.\FahCore_11.exe -dir work/ -suffix 02 -nice 19 -priority 96 -checkpoint 15 -verbose -lifeline 3596 -version 630'

[18:24:45] 
[18:24:45] *------------------------------*
[18:24:45] Folding@Home GPU Core - Beta
[18:24:45] Version 1.24 (Mon Feb 9 11:00:12 PST 2009)
[18:24:45] 
[18:24:45] Compiler  : Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 14.00.50727.762 for 80x86 
[18:24:45] Build host: amoeba
[18:24:45] Board Type: AMD
[18:24:45] Core      : 
[18:24:45] Preparing to commence simulation
[18:24:45] - Looking at optimizations...
[18:24:45] - Created dyn
[18:24:45] - Files status OK
[18:24:45] - Expanded 98607 -> 492188 (decompressed 499.1 percent)
[18:24:45] Called DecompressByteArray: compressed_data_size=98607 data_size=492188, decompressed_data_size=492188 diff=0
[18:24:45] - Digital signature verified
[18:24:45] 
[18:24:45] Project: 5716 (Run 2, Clone 10, Gen 108)
[18:24:45] 
[18:24:45] Assembly optimizations on if available.
[18:24:45] Entering M.D.
[18:24:51] Tpr hash work/wudata_02.tpr:  2984787093 3402003896 2675466090 1068714349 27619202
[18:24:53] Working on Protein
[18:24:54] Client config found, loading data.
[18:24:54] Starting GUI Server

[18:24:40] Gpu type=1 species=4. type 1 = ATI, species 4 = HD5xxx (will be 1 for HD2xxx, 2 for HD3xxx, 3 for HD4xxx, 4 for HD5xxx)

It didn't ask for nvcuda.dll ... and it doesn't even exist on my system ...

Taken from this thread -> viewtopic.php?f=51&t=15963

So, why does the download page not mention Gpu3 run's on 5xxx, but one client below ( gpu2 ) it does list 5xxx

And from that thread as well, why is the guide not clear on where to put the forcegpu flag ( yes it's mentioned somewhere, but not in first sight for a new donor ).

Now, Bruce reminded me in the past that high performance clients need donors with experience, and this should be enough reason to expect some familiarity with the normal clients to ensure people know how to for instance, apply flags. But is that still a valid position? How many new people want to start folding on their new computers with their top of the line graphics cards, even before trying a cpu client since they all hear that the gpu clients do so much scientific work? I would assume this is a large group of potential donors.

Still, the point is not about a particular problem or group of donors..

I'm trying to show how important it is that the download page and guides are current and easy to read. We almost lost a donor in that thread, and I'm sure we did loose allot of donors because of this in general, donors I can't point out because they gave up and didn't bother to ask for help ( ok not entirely our fault, they should ask for assistance ).

Now, Xilikon hasn't posted in a long time I hear ( I been away from forums and folding in general for a few months as well ) and I think only 7im could edit certain faq's and Xilikon could edit certain guides.

The problem is, we have the official guides which are set up through a kind of wiki but have very limited acces and rightfully so since they reside on stanfords own domain. And I can imagine Stanford being picky about who has acces to edit pages. But this brings us in the situation as it is now, where there seem to be a few issues which might not seem big but might still costs us donors. And each donor lost due to this has the negative side effect of spreading the word that 'our' clients are a pain in the butt ( yes, this is a general consensus amongst anyone not actually folding ). While most often the clients are not to blame, the information we have on how to configure and troubleshoot them is mostly to blame in my opinion atleast.

So, we also have an excellent fahwiki, also linked above the forums. And I see that for instance Panter_X has been adding valuable content there. The advantage of this wiki is that Stanford has no risk of letting people acces their portal, and it should be therefore much easier to get more people actively involved.

But, should I be promoting the wiki as place for guides, so we as a community have a better means of maintaining the content ourself, when the official pages link to guides which are not located on the wiki? No, that would mean I'm diversing locations of information, something I want to prevent.

So, I made this thread because I wanted to ask everyone to think about it and give some input.

• Do you agree the guides are not up to date ( and that this is a reoccuring problem with the current setup )?
• Would you agree a wiki hosted outside of Stanford would allow more active participants?
• Do you agree we should not spread the location of information, so it will be easier to maintain and easier to search?

If so, would it not be better to move all content which is up to date to the wiki, and dedicate ourself to maintaning it?

Offcourse I am not only looking for donor's opinions, I also would like to hear the opinions of the people now responcible for the guides/faq's as well as Pande Groups view on this matter.

And, if at any point we do decide to move everything to the wiki, for it to be succesfull there needs to be a large enough amount of people willing to help out there. And in those people we need those with the experience and knowledge to make it a work of art, eg we need our own community experts to help out. I think I don't have to name them; 7im for general info for instance, susato for anything related to a Mac, tear for some deep down under linux tweaking and the list could go on and on...

Are we as community able to set up and maintain a proper wiki with all the relevant info?

Let me know what you think!

[Nathan_P]

Edit: - Well and truly ninja'd by MtM tonight- besides his explanation is much better than mine

[MtM]

Nathan it's not just about the place to put new content, but more about if PG would support moving everything to the wiki if it proofs to be impossible to give enough people acces to the stanford portal itself.

[Nathan_P]

Nathan it's not just about the place to put new content, but more about if PG would support moving everything to the wiki if it proofs to be impossible to give enough people acces to the stanford portal itself.

Quite true, it has to be what is better for the guides in the long term - Putting them in the portal will only work if enough people have access, we don't want to be pestering PG every year because someoen has moved on and we need to give someone else access.

[MtM]

I sent Vijah an email with link to this thread and the question if he could comment. I'll do the same with UF/Bruce/7im

[7im]

Xilikon bailed on his little Guides project, and I have been making fixes when I have spare time. Stanford occasionally contributes to the Guides pages as well. In any case, I'll try to answer your questions.

So, why does the download page not mention Gpu3 run's on 5xxx, but one client below ( gpu2 ) it does list 5xxx

Stanford controls the download pages.

And v6.32 was tested to work on the NV platform. It was not tested to work on the ATI platform. You missed that topic while you were away. Yes, v6.32 seems to run fine on ATI cards, but as a policy, Stanford does not post software for hardware that is untested.

But the Install Guide for GPUs is up to date enough to cover that info.

3. 5xxx series GPUs are supported starting in the v6.23 FAH client, and requires the 9.10 Catalyst driver or newer. Also use the -forcegpu ati_r700 switch until 5xxx hardware is auto-detected in later FAH clients. Fixed in v6.30 and above.

Do you agree the guides are not up to date ( and that this is a reoccuring problem with the current setup )?

Yes, and No. Keeping documentation up to date is a never ending problem. However, they are more accurrate and up to date NOW than when it was Xilikon's project. For example, there was a completely new Install Guide page written for the release of the v6.30 SMP client just last month. http://folding.stanford.edu/English/WinSMPGuide Last Updated on September 02, 2010, at 12:26 PM

And if you think the guides are out of date, check the last edit date at the bottom of each Guide, and then tell me how out of date they are.

Also feel free to post suggested updates in each of the Client type Guides threads that Xilikon started. I follow those threads, answer questions there, and update the guides accordingly when people make suggestions. See the Linux install guide thread, for example: http://foldingforum.org/viewtopic.php?f ... 2&start=60 I just made two suggested updates there.

Would you agree a wiki hosted outside of Stanford would allow more active participants?

The FAH WIKI is ALREADY hosted outside of Stanford. So the answer to your question is NO by default. Free and unhindered access does not lead to better documentation, just more of it, and in more detail.

Do you agree we should not spread the location of information, so it will be easier to maintain and easier to search?

Yes, I agree with that one. Information should not be spread out any further than it is already.

Stanford does well enough with the Install Guides, and the General FAQs. If people what to GEEK OUT, I welcome them to add their expertise to the FAH WIKI, or post suggestions in the various forum threads. But the Stanford pages will never be a one stop shop for ALL information. If you piled all of the WIKI info in to the Stanford pages, the Install Guides and FAQs would be so drenched with and so long with information, that people would get overwhelmed, and they would be driven away even more so than a simple to follow but occasionally slightly out of date Install Guide or FAQ. Remember FAQ, as in Frequently Asked Questions. The IN-Frequently asked questions belong in the WIKI, just to keep things easy to read for the newer FAH members.

[VijayPande]

7im's been putting in effort and updating them regularly. I'll check back w/him to see if he still has time.

I think it's important that the guides be donor driven, since they're much more useful that way (that's why we have guides & FAQ's).

[MtM]

You make good points as always 7im.

Infact they are so good that right now I will not go into them all, just one and I will come back tomorrow with a fresh mind.

The problem is the navigation I recon, not so much the content. I followed the footsteps of the OP in the thread I linked, he followed the info given but it was not complete. It mentioned using the flag, it did not mention where ( untill you really start looking, eg it is not on the same page ). I can understand he got frustrated.

Adressing one other thing right now:

Free and unhindered access does not lead to better documentation, just more of it, and in more detail.

This is a good thing yes? If structured right, information is never overwhelming. So I disagree with a seperation of placement of content on the official guides and on the fahwiki. It's only crucial that you structure the information right, so that someone looking for a quick setup guide can find his info as well as someone who ran into an issue which is actually uncommon. ( edit: I do not disagree with the placement, that was wrongly formulated. I agree the guides should be quite minimal in appearance, but from the page this guide is on it should be possible to search for anything related to that client's setup. Like I said, if it only where possible to make a better information tree and make it possible to search both the guides and the wiki from one search field, that would go a long way! ).

Information should not be spread out any further than it is already.

If you agree with this, why not look at a better structure so that we can really centralize the information? The issue I have mostly is that you can not search the guides, you can search a wiki. A wiki setup is therefore better suited for information gathering/seeking.

Also, and I know I said just one point, but this one is a follow up, the guides are updated pretty recently I see, but how about all the translations? Will you translate the pages yourself? Or will Pande Group wait for another major client release (v7) and then ask for voluentueers again to translate the pages in other languages? A process that on a publicly accesible wiki would happen almost on it's own I feel.

Offcourse a wiki setup will need more active participants, not only those who contribute content but just as much those who check all contributions on accuracy and reliability.

I have more but that will wait for now, it's 0:28 and the dog needs to go out before I can sleep

[PantherX]

In the current situation, a donor had to bounce between Standford (Client download & Simple Guides lacking some information) -> Forum (further questions) -> Wiki (additional information that isn't covered in the simple guide but is required for the Client to run). That may overwhelm a user as they have to jump through some hoops to get the required information. Now my take on this situation is this:

Standford -> Download Clients, Simple and basic Guides (KISS)
Forum -> Detailed guides which are linked from the basic Guide (for easy access)
Wiki -> Additional information that a new user doesn't need. i.e. usages of important switches are mentioned in the Forum Guide while not frequently used switches like -delete X, -license, -queueinfo, etc. are mentioned in wiki, like 7im suggests "people what to GEEK OUT"

Now since 7im is doing an incredible job (Kudos dude) with the Official Guide, my suggestion is that the Forum have detailed Guides that are managed by users that have interest in them or are experts in that setup (like tear, hyperlife, etc). These detailed guides will have more additional information that a user may require if:
1) Want to optimize their contribution so use ATI Environment Variables
2) Want to know what common errors are there and how to troubleshoot them
3) Want to have a more detailed information
...

Now at the end of the Forum Guide, there should be link to the related wiki pages (if they are too many, link to the main page will suffice) so the flow of information would be like this:
Official Guide (for new users so it is simple) -> Forum Guide (advance users so is somewhat complex) -> Wiki (enthusiast users so no worries about level of detail )

For example, if the Official GPU Install guide has this:

For More Information, Please See:

• * NVIDIA FAQ
  * ATI FAQ
  * FAH FAQ
  * Further detailed information on GPU3 BETA Client for ATI/Nvidia GPUs

Once the user has read the entire guide and wants some more information, they click on the last link and are directed to my guide which does contain additional info that they may find useful. Also if they have a question, they can browse the guide/sub-forum to see if they can find the answer that suits them.

Now I would suggest that each Client has their own (sticky) Detailed guide in their sub-forum and that detailed guide is being updated by that user to cover as much information that is common. The only exceptions are events that a common user doesn't come across which should be reserved for the Wiki. Now the issues arises about constant updating. Here is my take:
Guide Leader -> Single donor that manages the post
Guide Updater(s) -> Donor(s) that will help the Guide Leader to write and maintain the Forum Guide. That way, it won't become too much on a single user and as the work is distributed among others, it won't overwhelm the single user so updates can be done within 24 hours of new information being available.

Now if for some reason the Guide Leader goes on vacation, the Guide Updater(s) can PM the revised version of the Guide to an admin/mod and they can update it. Once the donor returns from vacation, they can go through the Guide to see what has changed. However, these Detailed Forum Guides should be locked so that there isn't any unnecessary cluttering of the thread. If the worst comes and the donor can no longer continue to update the guide, they can ask someone else to fill their place. Since the Guide Leader can't update, the current thread is deleted and the new Guide Leader makes the post and that thread is locked once the updates are done. Now the major flaw with this idea is that the locked post can't be edited by normal users so maybe the Guide Leader is give sufficient privileges to edit the locked thread in that sub-forum only (would be nice to see what bruce can do, like a new group of members called Guide Leaders )

[7im]

...the guides are updated pretty recently I see, but how about all the translations? Will you translate the pages yourself? Or will Pande Group wait for another major client release (v7) and then ask for voluentueers again to translate the pages in other languages? A process that on a publicly accesible wiki would happen almost on it's own I feel.

Offcourse a wiki setup will need more active participants, not only those who contribute content but just as much those who check all contributions on accuracy and reliability.

I need to correct some of your assumptions so that you can draw better conclusions.

You CAN search the guides, because the F@h web site is filled with content from a type of WIKI backend. Use the F@h web site SITE SEARCH link, listed on the left hand column of every F@h page. If the search finds the string you are looking for, it will display a link to the pages that contain it. Try -forcegpu for example.

As for translating all of those pages, no, I won't be doing that. We have more than 30 volunteers updating the F@h web site in 16 different languages last time I checked. And the site search works for all the languages.

And anyone who wants to contribute, and who demonstrate an aptitude and attitude conducive to supporting this project through their writing skills are more than welcome to contact Vince Voelz of the Pande Group. Please note that active participation in this forum, and contributions to the FAH WIKI might be part of what they consider before bringing you on board.

[BikerBry]

It seems to me that many of you look at this from entirely the wrong perspective.

!. Who is the guide written for? - People that already know how to use it? Rediculous - The guide is just that a guide to install and use the client. Right? So it needs to be complete and concise, right?

2. To assume the guide is fine and all you have to do is "search" the info when it should be made accesable at the point it is needed is also rediculous.

3. Why all the redundant work? Should be a "One stop" resource. Linking everyone away from the original install is not productive, it's frustrating and time consuming. If you were to write a repair manual, would you stop at some point then direct the reader away from the manual to go to another resource for the rest of the info about the VERY topic you are trying to explain? Why even bother writing it in the first place if the information is incomplete?

I am telling you as someone who just walked into this that the guide is incomplete. All the info might be there (somewhere), but to assume everyone is going to understand a LOT of the Jargon you use and particular information is left out "intensionally" because it is somewhere else (who knows where?) is flawed reasoning.

Believe me, I understand the enourmous amount of work it took to get it to where it is today, I am only trying to help you see it from a perspective of someone who see the fundamental flaws from a person that just wants to fold and contribute and doesn't want to spend a month searching websites and posting 14 pages in a forum just to figure something out that there is supposedly a guide for.

Believe me, I DON'T want to be made a fool out of or made to feel stupid because I am pointing out my views on this subject, I KNOW I'm not stupid and I have read enough repair manuals to make you sick. I pull wrenches for a living and I LIVE in manuals and guides.

[7im]

Hello BikerBry, thank you for your feedback about the guides pages. I will address some of your questions, but not in the same order you asked them.

First, we don't assume anything. I did not say the guide was fine, and I was not suggesting that one should search their way to answers. I was correcting a mistaken assumption that MtM had, when he said the guides were not searchable. That's why I quoted MtM's post. In fact, the guides are searchable, if one wanted to do so.

Second, not all guides are written the same way, which MtM's feedback about the guides pages seems to overlook.

For example, the CPU client install guide is written for the beggining fah user, as that client is where most people start with this project. It is very concise and complete, and the client is very stable and mature, as is the documentation.

At the other end of the spectrum, we have the High Performance clients, like the GPU client. And that client can only be downloaded from a secondary download page, behind the first download page, and that 2nd page is full of warnings about this client being a high performance client, and that it takes up a lot of system resources. It also says that this client was for folding experts, which suggests this client may not be for begginners like yourself. And while the GPU client install guide is written for both the beginner and the expert, there may be a few assumptions in that GPU guide that are slightly above the beginner level. Hence the warnings and suggestions to also consult the FAQs before running a High Performance client, so that you can become an expert if not already an expert. In other words, read all the manuals.

And being new to the project, you are not aware that the GPU client is just out of beta testing, and still evolving, still being updated quite frequently, which makes keeping the documentation up to date a bigger challenge for an all volunteer group. Not an excuse, just that was it is.

And as I noted in your thread, the install guide main page does suggest that any questions about the install guides could be answered here in this forum. As you said, not everyone knows all the jargon. Some may not know any jargon. But even the best guides for computers, still use some jargon. You'll always need outside references for any documentation about technical procedures.

I also agreed with you in your thread that some improvements could, and would be made to the GPU install guide page regarding the use of the -forcegpu switch.

Again, we appreciate the feedback from "fresh eyes." There is nothing wrong with being a fah beginner, and nothing wrong with admitting that. We were all once a fah beginner in the past. An no need to feel bad for needing to ask beginner level questions about an expert level client. But let's not make the mistake that all guides or that all clients are the same. Just as I wouldn't assume being able to change my oil, plugs and air filter makes me an ASE certified auto mechanic.

So to summarize, the GPU client is slightly above the beginner level even though we try to write for that beginner level. And that we have plenty of resources to assist people who need help, and that we'll try to make the documentation better because of your feedback.

[MtM]

7im, how many people would use the search function on the stanford portal to look for setup info? I might have known it's 'searchable' that way but it's not in plain view for most people.

I think PanterX has putten forward some good suggestions, I need to read the post again and try working it out in an example or so but I think he has hit the nail on the head.

Especially with his opening paragraph which describes exactly the situation I would like to prevent happening in the future ( no I should be more carefull.. rephrase coming up ).

Look, I am not the person to actually change anything or set things up, by own admission I'm not stable in participation and contribution levels.

But, even when I know you are 7im, the problem I see is that the work is to much for one person.

You suggest contacting Vince, now I knew that but who else? Did PanterX already know he could ask someone from the Pande Group for acces to the guides/faq's? I think he shown he would deserve it.

So this thread isn't so much about me saying we need to change this, that en then some, but more to bring it under the attention of the whole community that their contributions count. And I want to make a point with the thread I linked to, that even while the information is certainly there, it's not easy to navigate.

We would benefit if the information tree was better charted, at this moment even people who have been folding for a long time have to go through hoops to find some information of intrests, just because the location of the information isn't always clear.

I'm not even saying you're wrong 7im with making the diffrentation between Frequently asked questions and IN-frequently asked questions, you're not, but I am saying that both questions should be searchable from one central point.

If it would be possible to search both the guides and the wiki from one search box, wouldn't that improve the situation allot already?

As I said, structured information is never overwhelming, information presented in enourmous chunks, without a well thought out index and reference chart is overwhelming since people will get lost searching for the small part they want to find.

I don't have an exact answer, and I won't pretend to know exactly what to change and how, but I do think my point is valid.

So, I hope more people will share their thoughts here, especially those people who I mentioned before ( tear or hyperlife for instance ). Those are the people who I would expect to contribute, so those are the people who should think along when I question how the information should be structured and presented.

[Nathan_P]

Just a couple of quick thoughts for now, the guide should be a one stop shop for all setting up info relating to that client, however in the case of the gpu client i think it should be split - Nv cards need a lot less setup that AMD/ATI cards do at the moment and this should be reflected as such.

[MtM]

7im, take a look at this:



Uploaded with ImageShack.us

Would you not agree that even while the content is searchable, that the method used is not helping much? I used your search phrase "-forcegpu", the amount of hits is overwhelming and I can't imagine it being usefull to search for something, then having to search a return query so large as this one

Searchable is only part of the question, if the search returns the information in a manner which is easy to navigate is the other part and there it fails in my opinion.

Now as I said, this is critisism but not towards you or your efforts, nor towards any person or his efforts. It's only critisism towards the functionality of the search function/layout.