For planning & discussion of purpose, goals, and content requirements

I think the general purpose/goals are established in other threads. As for content, we need a good idea of all the things we'd like to have (eg, collecting ideas then filtering them).
Once the desired content is established, then it can be formed into a hierarical structure.



the most obvious for the user guide are installation walkthroughs and links to errors/problems which might occour during the process with ways to fix any issues that come up.

probably best to have it as a side-article, but some discussion on the pros/cons of each type of installation, so users can make a more informed choice which better fits their needs.



for the reference, things like the actual spec of the app_info.xml file

ideally details on how things work (such as how the schedulers make decisions described in plain english (with the maths equations as a technical suppliment)

---

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

Thanks for starting a thread just on overall organization.

The idea here is to discuss and coordinate all the BOINC documentation efforts (or at least those that we can have some influence over).

I think it's clear there will be some "authoritative" reference at Berkeley. They might also host a "User's Guide" as a separate item, if we give them something worthwhile. Or it could be hosted elsewhere.

A part of the reason for separate sites is that because of the volunteer nature of BOINC in general you only support what you are able to support with available manpower at Berkeley, and you have to allow that volunteer efforts may come and go as people's interests change. Having more than one person doing the work can compensate for that somewhat. And then there is the issue of quality control.

I've suggested dividing the UBW into 3 major sections, for volunteers, project developers, and code developers, but there are other alternatives. It might be best to have the UBW be only for the volunteers, and have developer information on a completely separate site (or two?).

---

-- Eric Myers

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

Eric Myers wrote:

The idea here is to discuss and coordinate all the BOINC documentation efforts (or at least those that we can have some influence over).

I think it's clear there will be some "authoritative" reference at Berkeley. They might also host a "User's Guide" as a separate item, if we give them something worthwhile. Or it could be hosted elsewhere.

A part of the reason for separate sites is that because of the volunteer nature of BOINC in general you only support what you are able to support with available manpower at Berkeley, and you have to allow that volunteer efforts may come and go as people's interests change. Having more than one person doing the work can compensate for that somewhat. And then there is the issue of quality control.

I've suggested dividing the UBW into 3 major sections, for volunteers, project developers, and code developers, but there are other alternatives. It might be best to have the UBW be only for the volunteers, and have developer information on a completely separate site (or two?).

I posted my thoughts on these issues in BOINC FAQs

I believe that the user guide should be on the berkeley site, and if it's really got to be on a seperate site; detailed developer info elsewhere (see the linked post for my reasons). Having them both on the same site would be better, under 2 main sections ("guide" and "reference").

This all depends on the ability to make the berkeley site into something decent, otherwise it's useless.
Considering that, before we start planning around the idea of using the berkeley site, lets establish that it can be used as intended so we don't waste time having to re-plan.
Who do we need to contact about this? Dave Anderson, Rom?

---

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

This all depends on the ability to make the berkeley site into something decent, otherwise it's useless.

Trac is open to anybody, though you do now need to register. So we can work on improving the Trac wiki documentation.

That may be best thought of as the Reference Manual.

I would expect that they would only be interested in hosting something else at Berkeley if it was already in good shape and easy to maintain. There was some talk at one point about Berkeley hosting what is now the UBW, but they didn't want it in the form it was in, and that may in fact be when "Unofficial" was added to the name.

So I think it's better to try to construct something useful, and not worry about where it might be hosted. That can change, as appropriate.

Who do we need to contact about this? Dave Anderson, Rom?

Yes, and they might even read this section, but I would rather not bother them with details and instead try to come up with a good overall plan and present it to them for comment. They have lots to do, let's not take up their time until it's really necessary.

Of course they are always welcome to jump in to this disucssion if they wish, or to just read but not comment.

---

-- Eric Myers

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

(Man, I miss the feature on Pirates where it jumps to the end of a thread you've already read. I'll have to get those patches to Rytis. :-)

---

-- Eric Myers

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

Eric Myer wrote:

Lee Carre wrote:

This all depends on the ability to make the berkeley site into something decent, otherwise it's useless.

Trac is open to anybody, though you do now need to register. So we can work on improving the Trac wiki documentation.

Ah, excellent. The next problem is how users are going to get there, or even find it?

That may be best thought of as the Reference Manual.

I'm actually warming to your way of thinking now. If it's a reference then it doesn't need to be publicly advertised, and knowledge of it's existance will spread via word of mouth in the formus (I assume?)

I would expect that they would only be interested in hosting something else at Berkeley if it was already in good shape and easy to maintain. There was some talk at one point about Berkeley hosting what is now the UBW, but they didn't want it in the form it was in, and that may in fact be when "Unofficial" was added to the name.

Well, that's that's a bit cheeky considering the official boinc site leaves a lot to be desired, and something is better than nothing. But I see their point.

So I think it's better to try to construct something useful, and not worry about where it might be hosted. That can change, as appropriate.

I've always said high-quality content is essential.
But as for having the main (and rather important) user guide elsewhere won't be that bad as long as users can find it easilly, and it's well known about; by that i mean having prominent links from boinc.berkeley.edu and similar so users can jump straight to the guides once they've downloaded the installer.
I agree that hosting can change, and is somewhat irrelevent (as long as it's good & stable, and the URLs won't be changing; they do matter).
In the meantime where can we host our rough version while we're tweaking it?
I could host it on my own server at home, but it can't sustain high-traffic, it would be for demo purposes only, as a mock-up of the navigation for example.
I suppose no option is ideal, because it's hard to avoid a single point of failure (eg, the admin with control).

Who do we need to contact about this? Dave Anderson, Rom?

Yes, and they might even read this section, but I would rather not bother them with details and instead try to come up with a good overall plan and present it to them for comment. They have lots to do, let's not take up their time until it's really necessary.[/quote]Agree.
So as a seperate project, how are we going to go about hosting it?
I'm not saying we should jump into hosting right now (quite the opposite, the plan needs to be done first), but i'm just thinking ahead; I find it helps avoid issues down the line if you can see problems coming :)

Of course they are always welcome to jump in to this disucssion if they wish, or to just read but not comment.

I assume they all know it exists considering it was one of them who created this froum section.

---

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

Man, I miss the feature on Pirates where it jumps to the end of a thread you've already read. I'll have to get those patches to Rytis. :-)

That was quite a handy one, but seemed to be implementation specific, and very sensitive to changes in the code when a project customised things.

It's JavaScript dependant isn't it? That'll have to be changed to use a better - at least; more accessible - method. You Can't Rely on JavaScript Being Available. Period.

Why aren't the patches in the CVS anyway?

---

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

It's JavaScript dependant isn't it? That'll have to be changed to use a better - at least; more accessible - method. You Can't Rely on JavaScript Being Available. Period.

Yes, it uses JavaScript, and I agree that you cannot rely on JavaScript. Thanks for a link backing this up. What you can do is have optional features which use JavaScript to make the experience nicer. But the site must work with JavaScript turned off, and that should always be tested.

Why aren't the patches in the CVS anyway?

I test them on Pirates, then submit them to Rytis for his consideration. I've been slack about the latter step.

---

-- Eric Myers

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

Appologies for my rather long absense, other projects demanding my attention/time and all...

It's JavaScript dependant isn't it? That'll have to be changed to use a better - at least; more accessible - method. You Can't Rely on JavaScript Being Available. Period.

Yes, it uses JavaScript, and I agree that you cannot rely on JavaScript. Thanks for a link backing this up. What you can do is have optional features which use JavaScript to make the experience nicer. But the site must work with JavaScript turned off, and that should always be tested.

Absolutely right. There is infact a whole methodology to producing accessible, un-obtrusive JS which (should) work cross-browser etc. (like all good coding should).
It uses DOM methods which is the standardised way of applying JS to different browsers, eg having a standard language and "API" as it were.
the JS should be in an external .js file, referenced in by a <script type="text/javascript" src="absolute or relative URI">.

making it accessible includes using methods which aren't mouse-specific (or any pointing device for that matter). using "active" functions/triggers instead (eg like CSS "active" instead of "hover").

progressive enhancement (formerly graceful degradation) is a style of coding to make sure that JS will only be a factor if it's avalable in the first place. Removing much need for "testing/checking" etc. although basic testing should still be done, proper methods remove much of the need to test every possible situation as is the case with "dis-graceful degradation".
same idea as using valid code - removes the need for lots of testing in every version of every browser.

there's loads of info about writing good JS if you know where to look (but that article - by a standards advocate - is the best i've seen because it highlights the fact that the user doesn't always have control over javascript availability, so remarks like "you need to enable javascript in your browser" are instantly quashed :)
There are several books on the subject too actually. I can recommend some if you like.

Why aren't the patches in the CVS anyway?

I test them on Pirates, then submit them to Rytis for his consideration. I've been slack about the latter step.

Ah ok, you're busy, that's perfectly understandable :) I know the feeling ;)

Considering you seem to be the most helpful boinc dev who knows the code already; what would you recommend as the best way for someone very familiar with front-end code and usability to be able to apply changes to code which is predominantly back-end (server-side; PHP) based/oriented?

Because that's my major problem at the moment, I'm able to change simple things (like link text) but not the important stuff like page layout (migrating from tables to CSS).
Also PHP has it's own considerations for efficient ways of doing things etc.

---

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