A new member of our Pirates@Home crew has suggested that it is relatively easy to publish help documentation on the web in a form similar to the MS help system:

Peter Bradley wrote:

To give you an idea of what I mean I've knocked up a quick few starter pages (content shamelessly lifted from the Wiki and BOINC Web site). You can find them at:
BOINC v5 Help (example)

So I post the question here of whether this is a desirable thing to do?

One issue which concerns me is supporting multiple forms of the same or similar content. The wikis in use now allow for dynamic editing by a large number of volunteers, while it's not clear to me that this format has that feature. But if there is perhaps an easy way to package the wiki content this way automatcially....?

Anyway, I wanted to show this to people here.

---

-- Eric Myers

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

Link not loading for me, server timeout.

---

Link not loading for me, server timeout.

I got it to load via a proxy. First flaw: "To display this page you need a browser with JavaScript support". I enabled JS and got banner adversitements from no less than 3 ad servers. EDIT: that was the proxy's fault. They didn't have ads before, hmm...

---

Link not loading for me, server timeout.

I got it to load via a proxy. First flaw: "To display this page you need a browser with JavaScript support". I enabled JS and got banner adversitements from no less than 3 ad servers. EDIT: that was the proxy's fault. They didn't have ads before, hmm...

Well, that's one strike against it. I don't like the idea of requiring JS just to get help.

---

-- Eric Myers

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

Ok, finally got it to load the real thing (with CoralCDN caching proxy).

Like I said before, first flaw is that it's totally unusable with Javascript off.

The software used is from www.flyskysoft.com. I see Buy links everywhere, next to Download links. It's not clear what exactly the "free" version would lack, but the buy page says "Registration Benefits: Use the software without any function limitation", so I can assume the free version has function limitations.

As for duplicated content: lately I have been looking at Docbook. Its main advantage is creating HTML/PDF/manpage/whatever from a single file, and writing new converters should be possible. For example, given that "books" are nicely divided into "sections" (nestable), it's possible to extract a TOC to show on the left like on Peter Bradley's page. And it might be possible to convert Docbook into wiki formatting as well.

Problem is, it's definitely not as simple to edit as wiki formatting code. Docbook is also extremely oriented to giving the semantic structure; formatting is totally handled by the converter. There are no bold, italics, or typewriter-font tags at all. Instead, there are code, tag, parameter, variable, command name, etc. tags. It's up to the converter (and the way it's configured) to convert that into proper formatting.

And it would never be like a wiki anyway; as in, automated web app where users can edit.

---

Finally got a login sorted!

Couple of points.

First, it's me that's suggested producing help in this format, so I'll try not to present any arguments either for or against. Rather I'll just stick to bare facts and let you decide - because you know your own needs better than me.

Second, to pick up Eric's point. No, producing help in this format wouldn't be co-operative in the way that a Wiki is. Co-operation is the strong point of a Wiki (and sometimes its weakness, as well :) ). I think if you were to go for this, you'd have to only use it for docs that were pretty static and perhaps delegate the responsibility for creation and updates to one or more volunteers. Obviously it can be done, but it would need to be managed.

There's also the question of the tool to do the work. I have a license, but there'd be a need for more if it was adopted. But I'd fork out for at least a couple more, personally, to prevent that being a problem. It's not expensive.

Finally, Nicolas, yes it does require Javascript, which is one reason why I'd never suggest that it be the only format on offer. Glad you sorted the ad business. You had me worried for a minute then. And apologies for the slow speed of the server: it's on a low-speed site that I keep for mock-ups, examples and drafts for my private projects. It's never been a problem before - probably because I've never had a customer in Argentina (where some very good friends of mine live, BTW).

HTH


Peter

lately I have been looking at Docbook.

Me too. I went for this solution instead because I couldn't see an easy way of adding navigation/contents/index facility, and I was in a hurry. If that can be done easily in DocBook then it'd be a better solution (IMHO) - especially as it would be free (in both senses).

EDIT: Sorry, I meant adding contents/index/search facility. Of course you can do navigation in DocBook (D'oh)! I like the cumulative index and the search facilities - but that's just a personal POV. YMMV.


Peter

On the other hand, these are clean and clear pages with an equally clean and clear index down the side and always visible.

The thing that disconcerts me about both the BOINC Wiki and the Unofficial Wiki is the lack of an always-visible index/menu/tree, so I never know where I am within the whole. Maybe there's a way to make them appear and stay there, and I just haven't discovered the way.

Proliferation of help compilations isn't necessarily a disadvantage if somewhere or other there's a list of all the available & maintained compilations.

I saw it completely without ads. Is this what we are all looking at?

http://www.peredur.uklinux.net/BOINC5Help/

I saw it completely without ads. Is this what we are all looking at?

The ads were being added by the open proxy I used (note I edited my post saying so). I had to use a proxy because the page didn't load normally. I changed to another proxy (and added mental note not to use youhide again) and it worked just fine.

---

Since this is a .chm file converted to HTML(+JS) for presentation on the web, I wonder if it might have another use: to prototpye a small subset of help pages which could then be bundled with the client for Windows, and viewed with the Windows help tool. Yes, there are also web pages available for help, but this would make it possible to send a subset which could be of use on a client machine when it does not have a network connection, or which could present faster because they don't depend on a web connection.

---

-- Eric Myers

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

Since this is a .chm file converted to HTML(+JS) for presentation on the web, I wonder if it might have another use: to prototpye a small subset of help pages which could then be bundled with the client for Windows, and viewed with the Windows help tool. ...

That's an excellent idea.

---

Kathryn :o)

Since this is a .chm file converted to HTML(+JS) for presentation on the web, I wonder if it might have another use: to prototpye a small subset of help pages which could then be bundled with the client for Windows, and viewed with the Windows help tool. ...

That's an excellent idea.

Yes, excellent idea.
I've always found it mildly irritating to have to dial-up after pressing F1 in any Windows program. And right now F1 in the manager only leads to BOINC home page.
Maybe a Wiki page can be setup for the BOINC help. It could be polished by Peter Bradley and folks with Windows knowledge in various areas within BOINC.

Then maybe a very informative .chm could be created.

---

I wonder if it might have another use: to prototpye a small subset of help pages which could then be bundled with the client for Windows, and viewed with the Windows help tool.

Don't see why not. Would there be any point in also bundling the same thing in HTML format for the Linux client - if the idea is to save a dial-up (i.e. open a browser on a file location in the install tree)?


Peter

Well, that's one strike against it. I don't like the idea of requiring JS just to get help.

I think there's a couple of points to be made here.

First, I don't think there's any suggestion that this should be the only, or even the main help system. So there would be no question of requiring JS just to get help - only of requiring it to get help in this format.

Second, given that other help systems would remain, the noscript text could contain a link/links to to other source(s).

Finally, I'm not sure how much of a disadvantage it is to require JS, in these days of AJAX. It's a knockout punch for some users, of that there is no doubt, but provided they are catered for in other, easily accessible, ways I would be able to live with that: but YMMV.

Cheers

Peter

Would there be any point in also bundling the same thing in HTML format for the Linux client - if the idea is to save a dial-up (i.e. open a browser on a file location in the install tree)?

That was my next question. Windows is most-used client platform, so improving help for that is a worthwhile thing in itself, but if we could do the same for Mac and Linux so much the better. One way is to bundle these help pages as HTML and start a browser to show them. The other might be if there are tools for displaying the .chm version. That seems more likely on Mac than Linux. And of course whatever is displayed would have to be the Mac or Linux version of the F1 help pages.

---

-- Eric Myers

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

The other might be if there are tools for displaying the .chm version. That seems more likely on Mac than Linux. And of course whatever is displayed would have to be the Mac or Linux version of the F1 help pages.

This might be of interest:

xchm

I know nothing about it other than what it says at the url above. And, of course, its presence on a user's machine would be unlikely.

So this is just to note that such a thing exists.

Cheers


Peter

This might be of interest:
xchm

It's GPL, and works on both X11 and Mac. Both good. If it's small, it might just get bundled in with the document content. Then we could have substantially the same F1 help pages - locally available - on all three platforms. Not bad.

---

-- Eric Myers

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

It's GPL, and works on both X11 and Mac. Both good. If it's small, it might just get bundled in with the document content. Then we could have substantially the same F1 help pages - locally available - on all three platforms. Not bad.

Would you like me to play around with it on Linux (SUSE 10.0)?


Peter

Finally, I'm not sure how much of a disadvantage it is to require JS, in these days of AJAX. It's a knockout punch for some users, of that there is no doubt, but provided they are catered for in other, easily accessible, ways I would be able to live with that: but YMMV.

In these days of AJAX, I use the NoScript plugin, which blocks Javascript for all pages except those I explicitly add to the whitelist.

---