I think it would be useful to take an inventory of what documentation exists "out there" for BOINC, as the first step in:

1. See what we have
2. Decide what we want to have
3. Figure out how to turn what we have into what we want

Given that the work is all done by volunteers, step 3 needs to be evolutionary rather than revolutionary.

So for starters, we have

* Official Berkeley docs (in Trac wiki)
* Unofficial BOINC wiki
* BOINC FAQ site
* Spy Hill web pages
* CERN wiki pages


As I've already told David, I'm happy to see the stuff on Spy Hill moved into the other sites. It's just been easier for me to collect what I've learned where it is now.

Another question is whether (in the long term) there should be only one wiki (presumably at Berkeley) or if there is a reason for having more than one? I can think of good arguments for both.

---

-- Eric Myers

"Education is not the filling of a pail, but the lighting of a fire." -- William Butler Yeats

Eric, could you please give us active links to all 5 collections?

As I mentioned in another thread, at cpdn MikeMars led us to compile a set of 5 project READMEs:

http://www.climateprediction.net/board/viewforum.php?f=36

The items within the READMEs could be subdivided into

1) non-boinc info relating to the cpdn science or peculiarities of the project workunits ie not relevant to boinc documentation

2) boinc discussion and solutions probably only of use to cpdn crunchers (because of the length of the cpdn workunits)

3) boinc discussion and solutions probably useful to boinc crunchers in general

I am sure we at cpdn could compile separate lists for 2) and 3) if this would be useful.

---

I think it would be useful to take an inventory of what documentation exists "out there" for BOINC, as the first step in:

• See what we have
  
• Decide what we want to have
  
• Figure out how to turn what we have into what we want
  

(how do you create an ordered list?)
I would suggest the reverse, decide what we want first, so it's not influenced by what we already have. All too often i see "redesigns" which are just modified versions of what's already there because the team didn't start afresh.
By all means take anything useful from what already exists, but only after it's been decided what's needed, thinking in ideals ignoring any technical limitations which can be looked at later when it comes to implementation.

Given that the work is all done by volunteers, step 3 needs to be evolutionary rather than revolutionary.

Agree, so far the "revolutionary" approach has repeatedly failed, with site after site trying to be the "all-new, only resource you'll ever need" type thing. Collaboration is always evolutionary, but I suggest this doesn't mean the creativity and ideas need to just be modifications of the existing state of things.
I'd say revolutionise the structure, process (eg editorial process), but evolve how we all go about it.
The first issue is where to host the improved resource, and a general idea of how it's going to be done (eg, what technology is it going to be based on?)
Or even better, have a high quality site for discussion by all involved, work on content first (content is king) then once that's established decisions about hosting (which should be based on the needs of content) can be looked at.

So for starters, we have

• Official Berkeley docs (in Trac wiki)
  
• Unofficial BOINC wiki
  
• BOINC FAQ site
  
• Spy Hill web pages
  
• CERN wiki pages
  

As I've already told David, I'm happy to see the stuff on Spy Hill moved into the other sites. It's just been easier for me to collect what I've learned where it is now.

I think you've hit on an important point here; the lack of colaboration (for whatever reason). Things are very fragmented at present, yet it's more useful to have a central coherent resource (as long as it's good with high-quality content).

Another question is whether (in the long term) there should be only one wiki (presumably at Berkeley) or if there is a reason for having more than one? I can think of good arguments for both.

I'd like to hear them, from a usability point of view (again, assuming a good site with high-quality content) a single resource is easier.
However, different resources could deal with different subjects/areas; such as one for beginners etc. and one for developers containing more technical information & discussion about development of the software and web side of things (inc. documentation).

---

Want to search the BOINC Wiki, BOINCstats or various BOINC related forums from within firefox? Try the BOINC related Firefox Search Plugins

mo.v wrote:

Eric, could you please give us active links to all 5 collections?

Sure. In fact all of this should go on a single wiki page at some point.

---

-- Eric Myers

"Education is not the filling of a pail, but the lighting of a fire." -- William Butler Yeats

mo.v wrote:

Eric, could you please give us active links to all 5 collections?

I assume these are the correct URLs, please update if incorrect.

• Official Berkeley docs (in Trac wiki)
  
• Unofficial BOINC wiki
  
• BOINC FAQ site
  
• Spy Hill web pages
  
• CERN LHC@Home wiki pages
  

---

Want to search the BOINC Wiki, BOINCstats or various BOINC related forums from within firefox? Try the BOINC related Firefox Search Plugins

*Spy Hill web pages

The BOINC related help pages are all at http://www.spy-hill.net/help/boinc and under. That page itself is not a good entry page for guiding people to what they may be seeking, though it tries to make it clear that it is for application developers and project managers and to steer volunteers just running the client elsewhere. And those pages in general are not as well organized as they could be. They've just grown to be the way they are over time.

*CERN wiki pages

That is the top level of the CERN wiki, and it gives you an idea of what a Twiki wiki looks like. It can be divided into various "webs" for different projects. Those are all listed in the left hand nav column. I find this confusing and unhelpful. Somewhere in that mess there are some useful pages about BOINC from the folks who created LHC@Home, but searching for BOINC doesn't find them.

The pages I have bookmarked there are:

• Howto Compile Boinc Server
  
• LHC@home: Links, Documentation and Publications
  

As you'll note if you visit them, these two pages are in entirely different "webs". The good news is that there seems to be an entire "web" for LHC@Home.

---

-- Eric Myers

"Education is not the filling of a pail, but the lighting of a fire." -- William Butler Yeats

Eric Myers wrote:

Lee Carre wrote:

• Spy Hill web pages
  

The Spy Hill BOINC related help pages. That page itself is not a good entry page for guiding people to what they may be seeking, though it tries to make it clear that it is for application developers and project managers and to steer volunteers just running the client elsewhere. And those pages in general are not as well organized as they could be. They've just grown to be the way they are over time.

fragmentation is an example of what all too easilly happens without good information architecture design and maintainence :p

Eric Myers wrote:

Lee Carre wrote:

• CERN wiki pages
  

That is the top level of the CERN wiki, and it gives you an idea of what a Twiki wiki looks like. It can be divided into various "webs" for different projects. Those are all listed in the left hand nav column. I find this confusing and unhelpful. Somewhere in that mess there are some useful pages about BOINC from the folks who created LHC@Home, but searching for BOINC doesn't find them.

The pages I have bookmarked there are:

• Howto Compile Boinc Server
  
• LHC@home: Links, Documentation and Publications
  

As you'll note if you visit them, these two pages are in entirely different "webs". The good news is that there seems to be an entire "web" for LHC@Home.

I was just going by the link text, I assumed you wanted the main TWiki page, but i suppose i should have checked if it was appropriate. I didn't realise that it's a vast resource LOL

I've updated my original post with the new URLs

---

Want to search the BOINC Wiki, BOINCstats or various BOINC related forums from within firefox? Try the BOINC related Firefox Search Plugins

Lee Carre wrote:

I didn't realise that it's a vast resource LOL

And that is why it's good to take inventory. :-)

I've updated my original post with the new URLs

No need for that. This is just a discussion and we will take what we get from it and compose it into a more refined product elsewhere.

What is the re-editing timeout on this board?

---

-- Eric Myers

"Education is not the filling of a pail, but the lighting of a fire." -- William Butler Yeats

Eric Myers wrote:

Lee Carre wrote:

I didn't realise that it's a vast resource LOL

And that is why it's good to take inventory. :-)

very good point lol

Eric Myers wrote:

Lee Carre wrote:

I've updated my original post with the new URLs

No need for that. This is just a discussion and we will take what we get from it and compose it into a more refined product elsewhere.

Oh well, done now, and i'll leave it as it so it's a proper list of the resources

Eric Myers wrote:

What is the re-editing timeout on this board?

I believe it's an hour by default. Although I have issue with the idea of being able to edit for an hour, then not at all, not even to correct spelling/grammar errors, seems very counter-productive on the usability front lol

---

Want to search the BOINC Wiki, BOINCstats or various BOINC related forums from within firefox? Try the BOINC related Firefox Search Plugins

Lee Carre wrote:

Eric Myers wrote:

What is the re-editing timeout on this board?

I believe it's an hour by default. Although I have issue with the idea of being able to edit for an hour, then not at all, not even to correct spelling/grammar errors, seems very counter-productive on the usability front lol

I would actually like to see it shorter. As a scientist I'm used to writing in a logbook (either paper or electronic), and the convention is that you just write your observations and move on. Errors are never deleted, just corrected (with a new log entry) or perhaps made invisible. You just go on with it, and the logbook is a part of the input data stream.

You then take this raw data and digest it and put it into a nicer, more organized form. But that is a separate, new document, not the logs.

I've made changes to the software (see Pirates@Home) to support this kind of use for the I2U2 project, though of course we don't have to be so strict here in this discussion.

---

-- Eric Myers

"Education is not the filling of a pail, but the lighting of a fire." -- William Butler Yeats

Eric Myers wrote:

Lee Carre wrote:

Eric Myers wrote:

What is the re-editing timeout on this board?

I believe it's an hour by default. Although I have issue with the idea of being able to edit for an hour, then not at all, not even to correct spelling/grammar errors, seems very counter-productive on the usability front lol

I would actually like to see it shorter. As a scientist I'm used to writing in a logbook (either paper or electronic), and the convention is that you just write your observations and move on. Errors are never deleted, just corrected (with a new log entry) or perhaps made invisible. You just go on with it, and the logbook is a part of the input data stream.

You then take this raw data and digest it and put it into a nicer, more organized form. But that is a separate, new document, not the logs.

I've made changes to the software (see Pirates@Home) to support this kind of use for the I2U2 project, though of course we don't have to be so strict here in this discussion.

I do see the point of some of the ideas behind it, to reduce abuse (eg people editing messages a long time after they were originally posted in a way to make people who replied look bad, due to changing the context of their original message etc.) and the fact that things are set in stone (again, for replies etc.).

The problem is that this isn't the rough version which is then processed and presented nicely later. For usability it's horrible, corrections & additions occouring in new messages (which may not be read), the general flow of a thread can be really fragmented at worst.
Basically it doesn't play well with one of the fundamental usability rules; scanability.

I mean, I know I'm in the minority talking about usability (ie, the "prevent abuse" thinking has won because it's on the mind of more people, and those controlling, having access to, and/or able to edit the source code), but there's no escaping the fact that good usability is really important for a sucessful resource.

Think about your own experiences, and how long it can sometimescan take to find some useful/revavent information in a thread.

I suppose you could argue that the documentation is supposed to be the pretty version. And yes i'd agree with the idea that it's supposed to be, but we all know what usually happens to documentation ;)
If the documentation is intended to be the nice version of the collective knowledge, then again, it needs to be done really well if it's going to be at all effective.
I don't mean to sound pesimistic, I'm just pointing out things which aren't obvious at first, or not until after experience of how it can go wrong.
Usability in general covers both of those things unfortunetly, and trying to show measurable benefit is hard. To start with, what exactly do you measure? lol
Again, think of your own experiences; a common example is how long it takes a site to load; user's hate slow sites (which is essentially down to attention spans, something which can't be changed), I know i've been cursing sites which take forever to let me do something. But to measure the benefit of a fast site is hard; to justify it to the doubters.
Maybe loading time is a bad example, most peolpe realise that speed is very important (user's just leave out of frustration otherwise) but there are many other more subtle examples which don't get a second thought from those concerned about other things.
Unfortunetly the usual result is that usability suffers (greatly) and a not-so-useful resource is all that remains.

---

Want to search the BOINC Wiki, BOINCstats or various BOINC related forums from within firefox? Try the BOINC related Firefox Search Plugins

This was noted on the SETI@Home news feed. Add it to the inventory

* How-To: Join Distributed Computing projects that benefit humanity

---

-- Eric Myers

"Education is not the filling of a pail, but the lighting of a fire." -- William Butler Yeats

This was noted on the SETI@Home news feed. Add it to the inventory

* How-To: Join Distributed Computing projects that benefit humanity

Appologies for my rather long absense, other projects and all...

I came across that page the other week, the idea and layout seems good, but the underlying code is rather messy, check the validation result

---

Want to search the BOINC Wiki, BOINCstats or various BOINC related forums from within firefox? Try the BOINC related Firefox Search Plugins

Dimitris probably didn't put the document into a validation checker. You could email the link to him - his address is at the bottom of the page. There are a few minor details I may contact him about, but he's researched a lot of projects very thoroughly and it's a very worthwhile document.

---

A current confusion for members is that as well as the Unofficial Boinc Wiki

http://boinc-wiki.ath.cx/index.php?title=Main_Page

that is published in the usual wiki format, there's now also the TracWiki/BoincWiki

http://boinc.berkeley.edu/trac

which appears to be funded and published by BOINC in Berkeley. The latter is not in the usual wiki format, though it can be edited by any member (perhaps now with restrictions). My own view is that it was a mistake ever to include the word 'wiki' in the name of the Trac compendium.

If I've completely misunderstood something here, I would guess that the majority of boinc crunchers who've ever looked at boinc/unofficial/official/wiki/info/trac pages are equally confused about what is what.

To use wiki teminology, this needs to be disambiguated. Preferably by renaming ( both?), and NOT by interminable forum posts explaining which is which.

It's a pity we haven't got Paul Buck here to add an opinion.

---

Trac is maintained by Berkeley.

Wiki is a concept, not a piece of software. Most people are familiar with MediaWiki as that's what WikiPedia runs off of. But there are other Wiki packages with different sorts of functionality. Unfortunately people think the look of Wikipedia = Wiki. And that's just not true.


Trac is a whole system for the development team. And the wiki part of it really is a wiki. Its markup is a subset of Moin-Moin's markup.

All of the old .php pages have been migrated to the Trac wiki and they are no longer being maintained. All the documentation along with the source code and ticketing system are all in Trac. To me, it makes more sense than what they had before (php pages for documentation, CVS for the code repository and BOINCzilla for bugs).

Maybe changing the "wiki" tab to read "documentation" would work. I have no idea if that's possible within the constraints of Trac.

---

Kathryn :o)

Yes, that all makes good sense and it's a good idea to have all this formerly dispersed stuff accessible from a single set of buttons in Trac. But including the word 'wiki' in two different boinc compendiums will inevitably lead to confusion.

The well-known word 'Wikipedia' is an all-embracing encyclopaedia on a par with the E Britannica. And many people think that the word 'wiki' is just a short form of 'Wikipedia'. So if crunchers see more than one reference to boinc+wiki, many if not most will expect them all to refer to a single all-embracing compendium of boinc documents.

Which of course is not the case because there are now two.

A Google search for 'wiki' leads to descriptions of the software and to (more) links to compendiums.

The Unofficial Boinc Wiki has had this name for ages and should retain the word Wiki in its name on the grounds of prior use and the Wikipedia-like format of its pages. I think the documents accessible from Trac should be renamed.

---

The Unofficial Boinc Wiki has had this name for ages and should retain the word Wiki in its name on the grounds of prior use and the Wikipedia-like format of its pages. I think the documents accessible from Trac should be renamed.

I agree there is potential for confusion, but Wikipedia != MediaWiki != wiki. As Kathryn pointed out, a wiki is a general concept - a piece of software which lets a group of people edit documents collaboratively. And to do so easily and quickly. The name comes from the Hawaiian word "wiki wiki", which means "quickly".

The best way to avoid confusion is make this point clear.

Right now I deal with three different wiki's, and all are implemented with slightly different software and have slightly different markup conventions. It *is* a bit confusing to keep the three straight, especially as I was starting out. (I've been thinking of creating a wiki page with a table summarizing the differences. Where to put it?)

The Trac component which allows the community (as we define it) to edit documentation at Berkeley is a wiki, so there's no point in removing the name from the URL. It's the wiki at Berkeley.

The Unofficial BOINC wiki is also a wiki. I belive Paul was encouraged to include the "Unofficial" to distinguish it from anything hosted by Berkeley.
Perhaps there are other ways to distinguish it as well? But what we can't do is refer to "THE" wiki, because there are two.

What we _can_ do is try to distinguish the two by purpose and focus. I mentioned earlier the idea that the Berkeley pages could be thought of as being the "Reference Manual". They would be an authoritative source (it's from Berkeley) containing all information about BOINC, arranged as appropriate for a reference document. The UBW could play the role of the "User's Manual", which would be arranged more as a description of how to do the most common or most useful things, not in the form of a reference manual.

Now that's one way the two could be distinguished, but it doesn't have to be the way it's done. In any case, it would be useful to have clear guiding principles which distinguish the roles of the two.

And should there be only two? The idea has come up that it might be useful to have a completely separate wiki to document how to create a BOINC project and BOINC applications. The idea is to keep the more technical material separate from what the casual BOINC volunteer needs to know (which is what would remain in the UBW). In that case there might even be a third wiki in the collection of BOINC documentation.

So my main point is that we should not think of there being "THE" wiki, as there can be several. How best to make this point and dispel confusion among users is something we may still need to work out.

---

-- Eric Myers

"Education is not the filling of a pail, but the lighting of a fire." -- William Butler Yeats

But what we can't do is refer to "THE" wiki, because there are two.

Actually, there are even more than two. Adding in the German BOINC Wiki, the French one, another German one and having the probability of teams having their own Wiki and you see there's never any option of "THE" Wiki.

---

I wonder how many people even know Trac exists. There was a news item on the main page. But how many of the 10000s of crunchers actually read it?

I link to it in my sig on all of the project forums. But I have no idea how many people click through.

I tend to only tell people to go to Trac when they have a bug to report or I know where the documentation for something is. Like building BOINC using VS. I don't even know if there is a page on the UBW for that.

---

Kathryn :o)