RISC OS User Guide PDF

Some random observations:

Has there been any sort of decision regarding chapter layout?

Thankfully this guide doesn’t do the patronising “this is a mouse” which might have made sense in 80-something but we can assume that even children are au fait with mice these days… We perhaps ought to have a section highlighting differences between Windows/Linux and RISC OS – why “nothing happens” when you run an application, why there are no menus anywhere to be seen. That sort of thing.

Page 5. I understand what the app icon is because I’ve used RISC OS since forever, but looking at the text of page five, I’d have to ask – what the hell is that picture supposed to be? It might be better if the directory display screenshot on page 4 included a few applications and highlighted them as such.
Which takes us back to a fundamental difference between RISC OS and others – we don’t have a Start menu structure, or that abomination that is Unity. Applications are really directories in disguise and will be present within the filesystem.

I forget – how does one save a desktop start-up file these days? The procedure given (p53) is kind of clunky, but this stuff has been removed since then. There’s a “Desktop boot file” option in Configure → Boot but it is greyed out; though this is faulty on my machine, it complains that it can’t open “<Choices$Write>.Boot.PreDesktop” (doesn’t exist) and ignores the “Desktop” file…

I’m guessing the part about using floppies and harddiscs will need to be replaced with references to SD cards and USB media, perhaps with floppies/harddiscs briefly mentioned as “other fiing systems” thanks to the IOMD port.

Netowrking will need to cover LanMan and leave behind Econet. Do people use ShareFS and/or AUN these days?

Ooooh, printers. Does RISC OS speak to any USB printers without add-ons? Can it talk to an older parallel printer via USB to parallel dongle?

Chars – please can ROOL push through the updated Chars before this guide goes to press? ;-)

Perhaps sections on making and using SD images. Should value-added applications be covered? SwiftJPEG, Store, and NetSurf are not strictly part of the OS but deserve as much of a mention as Draw and Paint these days. (after all, ChangeFSI is covered…)

The official Pi SD card contains a lot of useful stuff – programming tutorials, charm, DrWimp, Lua. Should the guide make reference to these? A lot is being made of the likes of Scratch these days, so maybe examples of using RISC OS for something specific mightn’t be a bad way to get the ball rolling.

Something to consider is that our target reader is not somebody who has purchased a RISC OS computer, but now somebody who may be trying RISC OS and is used to other things. To this end, I think it is vitally important to cover differences “from the norm” as also to highlight ways to get stuff done using RISC OS.

Thankfully we have a really good user guide to get started with (frankly, better than anything I’ve seen supplied with boxed Linux bundles, nor Windows’ user guide, nor…).

Do people use ShareFS and/or AUN these days?

ShareFS: daily. Very useful. “Just works”.

I forget – how does one save a desktop start-up file these days? The procedure given (p53) is kind of clunky, but this stuff has been removed since then. There’s a “Desktop boot file” option in Configure → Boot but it is greyed out; though this is faulty on my machine, it complains that it can’t open “<Choices$Write>.Boot.PreDesktop” (doesn’t exist) and ignores the “Desktop” file…

You can do it from Task Manager’s menu. The Configure option should ungrey itself once the file exists, and it appears to open the correct file on my Pi (but I’ll need to double-check that as I’m running from memory here!)

I’m guessing the part about using floppies and harddiscs will need to be replaced with references to SD cards and USB media, perhaps with floppies/harddiscs briefly mentioned as “other fiing systems” thanks to the IOMD port.

That makes a lot of sense. My current updates have been around making the chapter match the OS (a lot of options have been renamed or moved), as opposed to adding new stuff. There’s definitely a lot of work to be done in the Configuration chapter!

The official Pi SD card contains a lot of useful stuff – programming tutorials, charm, DrWimp, Lua. Should the guide make reference to these?

Perhaps. I’ve added a (very sparse!) section on “CPU” in Configure, which I believe is Pi-specific, since it’s part of the “base OS”. I haven’t touched SpecialFX though!

Question: Does anyone know what the “surround” of a window is called? I’ve seen “window furniture”, “window border” and “system window area” in various places. The Style Guide doesn’t seem to name it officially; it simply says “parts of a window” and points to the various icons directly. I’ve used “window furniture” in my draft in the meantime.

And on a related note, is it correct to refer to the Apps icon in the icon bar as a “directory”? Configure calls it a folder.

You can do it from Task Manager’s menu. The Configure option should ungrey itself once the file exists, and it appears to open the correct file on my Pi (but I’ll need to double-check that as I’m running from memory here!)

“Configure…” option here…runs Configure. ;-)

Looking at the source, that is all that option does. The last time I needed to save a state, I faked it with a short program to emit the Message_SaveDesktop message.

Perhaps. I’ve added a (very sparse!) section on “CPU” in Configure, which I believe is Pi-specific, since it’s part of the “base OS”.

What you see on your Pi is Pi-specific. The OMAP3 version has a reduced set of options – Alignment faults on, or off. There’s no compatibility mode. I would guess similar for OMAP4. I guess a brief description and a note that what options are available here depends upon the hardware of the machine…

Question: Does anyone know what the “surround” of a window is called?

I think it is usually called “window furniture” (old people) or “chrome” (pretentious people). I’d avoid the latter as it is used for half a dozen things already these days – a browser, a browser language, a framework, an API, an OS…

And on a related note, is it correct to refer to the Apps icon in the icon bar as a “directory”? Configure calls it a folder.

Depends whose terminology you prefer. “Directory” is Acornish. “Folder” is Windowsish (also used by Linux, iOS, Android…). I think logically we should call them all folders now, but somehow I can’t help but feel that doing so would be something lost.

“Configure…” option here…runs Configure. ;-)

Poor wording on my part. You need to open the Task Manager window, and open a pop-up over it. You can’t do it from the icon bar.

As for my “ungrey” comment, I was referring to the “Desktop boot file” button in Configure→Boot.

I forget – how does one save a desktop start-up file these days?

You don’t unless you want Sprow to come round and kick you;-)

I said:

I’ve seen PDF’s done like that so they are only readable in softcopy and not printable

I note from the reader that’s secured now. “Simples”

While I can potentially see a reason for making the final copy non-printable, it’s not great for a draft: I can’t print the current version without a password and therefore can’t annotate it. Fortunately I still have the old version, but it has some of the images missing.

Today is a significant milestone (psychologically) for the RISC OS 5 User Guide because 50% of chapters are now complete – a big thank you to those who have engaged and submitted text or proof reading comments. Of those completed chapters by author we have:

• ROOL 19 (60%)
• Sprow 9 (28%)
• Chris Mahoney 2 (6%)
• Bernard Boase 1 (3%)
• Chris Wraight 1 (3%)

The User Guide is an easy way to get involved with the RISC OS Open project because it doesn’t involve any programming, a common observation from shows being that end users want to help but aren’t themselves coders. For example, there are 19 other authors commenting on this thread alone who have yet to volunteer to ‘adopt a chapter’.

The aim is to have this fully up to date for the next stable release since its last printed version in 1995, but that’s going to need more pairs of hands. The current draft is available on the downloads page.

Out of interest, has anyone managed to contribute to the wiki using NetSurf? I get an error about needing Javascript on every time I attempt to submit some changes. I get the same error sometimes with Chrome on a Mac, so wondered if it’s something I can work around. Using recent versions of both RISC OS and NetSurf, with JS enabled.

Not a big issue if this isn’t possible, but it would be nice to work on UG contributions and post the text from my Pi.

If watching re-runs of Dad’s Army over the holidays isn’t your thing, perhaps editing a chapter of the User Guide will offer light relief?

The User Guide is an easy way to get involved with the RISC OS Open project because it doesn’t involve any programming, a common observation from shows being that end users want to help but aren’t themselves coders. We’re most interested in the content (the words) rather than the layout, so drafting can be done in !Edit and emailed to userguide@riscosopen.org or pasted into the wiki page.

To date, there are 34 completed chapters and 29 left to go, in particular MineHunt and Omni are entirely missing. The others exist but require bringing up to date as they’re Frozen exactly where Acorn left them in 1995.

in particular MineHunt and Omni are entirely missing

Happy to produce a MineHunt page. Btw, did you get my email with the replacement Patience screenshots?

If watching re-runs of Dad’s Army over the holidays isn’t your thing, perhaps editing a chapter of the User Guide will offer light relief? To date, there are 34 completed chapters and 29 left to go…

Thanks to Chris and Sprow for their User Guide updates over the holiday period. Along with some ROOL edits, there are now only 24 chapters left to review and/or update. If you can write in a clear and concise style then this is a great project to get involved with, and something we want to have fully up to date before the next set of stable releases.

Today marks another psychological milestone with the progress of updating the User Guide prior to the next stable release of the OS.

80% of chapters are now complete – with a recent push from Chris Mahoney in particular. Accounting for those chapters already claimed or in progress there are now only 9 awaiting volunteers, so if any of the 25 voices in this thread wish to sign up (rather than commenting) now’s the time.

We’re also on the look out for minor edits from proof readers, with the latest draft here.

Too bad if you wanted to volunteer to write for the revised RISC OS 5 User Guide – 95% of chapters are now complete, and Chris Mahoney has bagged the last 2 (thanks Chris!). This update is holding up work on the next stable release of the OS (5.24) so if you’re bored over Christmas here’s how you can help:

• Review the outline of what’s happening
• If you spot minor typos just append them to the typos page
• Take on reviewing an entire chapter by adding your name to the respective row for that chapter

It’s OK for a chapter to be reviewed more than once, but it probably makes more sense to pick a chapter nobody else has reviewed first. Reviewing is mainly concerned with channeling your inner nitpicker to check the words match the chapter topic (eg. menus described match application reality, screenshots are the right way up, we ain’t used no double negatives, etc…). Spend at most 2h on a chapter – some only have 4 pages and will take more like 15 minutes.

With 5 already done, that leaves 55 chapters which isn’t a big ask.

Take on reviewing an entire chapter by adding your name to the respective row for that chapter

Application error (Rails)

Review the outline of what’s happening

Link gives:

404 Page not found
nginx

404 Page not found

Try the link as seen from the Software Information page.

I think it was a case of pasting in the URL as seen from the editors point of view rather than the general user.

Note 1, it’s pretty easy to check the spelling if you throw the text out a plain text file and then throw that at a PeeCee spell/grammar check.

The “starter for 10”, as the saying goes, is the typo on page 2 of the PDF where it reads “Pubished by RISC OS Open Ltd.” instead of “Published by RISC OS Open Ltd.”, and the contents pages have “Gettting out of a mess 124” with an extra “t” and “Achives 487” is missing an “r”

Now I just have to avoid the jobs SWMBO keeps finding and pull these together for a submission.

Once the Desktop chapter has been merged, I think it would be good for someone to have a look at how the different window interactions and keyboard shortcuts are introduced to the reader. E.g. at the moment I can see that both the “Windows” and “Desktop” chapters mention a lot of the window interactions, so it may make sense to adjust which interactions are mentioned where, or include cross-references so that a reader can easily find all of them.

I believe this wiki page has a full list of the window interactions, along with some common keyboard shortcuts, so should be a good reference to use when determining how complete the user guide is (feel free to ignore the NetSurf shortcuts, and any shortcuts which are listed in obvious menus)

Or maybe we should have an appendix which lists all of the interactions + shortcuts, so that individual chapters don’t get bogged down trying to list all the different variants?

Not many chapters have been reviewed at all yet so, given my relative RISC OS inexperience, I’ll start with a sanity check of Diversions. This trivial exercise will hopefully spur those more conversant with the OS into more substantial reviewing efforts!

I reviewed the 17 chapters in Beginner’s Concepts and Diversions. I’ll leave the rest for others to cast their eye over.

Beyond the scope of the reviewing that’s been requested to get 5.24 out the door I suggest there are two major things that need to happen for future User Guide revisions:

1. Completely remove the sort of text that assumes readers have never even seen a computer before.
e.g. “In a foreign restaurant, if you can’t actually speak the language, you can point at the menu with your finger to tell the waiter which dish you want (assuming that you know what the menu means!). On the computer, …”

2. Include more of the wealth of technical detail present in this forum that computer-savvy but not RISC OS-savvy users would find invaluable for getting to grips with the OS.

On the other hand, a beginner will always be a beginner.
I see everyday people that still don’t know how to hold a mouse or using Shift/Ctrl on a keyboard.

a beginner will always be a beginner

Now, now. People can improve. ;-)

Thing is, RISC OS no longer comes pre-installed on any machine, so the chances are that either the user installed it (so they know the basics) or somebody did it for them (and can teach the basics).

Phrasing these days must be careful. It is useful to introduce the third button on a mouse, as it is important to RISC OS, however describing what a mouse is for is a bit patronising. When RISC OS was new, nice were still fairly rare and one could navigate Windows3 without. Now? Mice and touchpads are fairly well known.

Hint – local library. I reported on my blog a while back that a saw a young girl getting on perfectly well with Wikipedia. And a mouse. And Windows… How young? She didn’t want to leave to have her nappy changed. That young.

Differences between RISC OS and other commonplace systems are perhaps now much more important than “this is a scroll bar”…

a beginner will always be a beginner

Now, now. People can improve. ;-)

I’m assuming David meant “there will always be beginners”, although with the number of pre-school kids familiar with such things the User Guide requiring reading skill might be the obstacle.

Thing is, RISC OS no longer comes pre-installed on any machine

I suspect people at RComp and CJE might dispute that statement.

It is useful to introduce the third button on a mouse, as it is important to RISC OS, however describing what a mouse is for is a bit patronising.

The third (middle) mouse button is a feature that needs heavy emphasis along with the effect of the right hand button.

When RISC OS was new, nice were still fairly rare and one could navigate Windows3 without.

When RISC OS was new, Windows was likely to crash at the slightest untoward thing, or even simply crash.¹

Differences between RISC OS and other commonplace systems are perhaps now much more important

Very much so, this is quite obvious when you read comments from places like the RPi forums with the implied “the GUI wasn’t like Linux, so I don’t get it”.
Note that standard Windows users think everything else is weird whether it’s the wavy finger stuff of touch screen systems or Linux or “what’s this Risk Oss thing?”
RO is just a step weirder from their viewpoint.

¹ Having thought back in more detail it should be stated that the first two incarnations of Windows were total **** and that v3.0 was barely acceptable. v3.1 was the first halfway usable product and RO had been around for five years at that point.

I suspect people at RComp and CJE might dispute that statement.

Fair point, but I wonder how many people buy from either who have never used RISC OS before?

Windows was likely to crash at the slightest untoward thing, or even simply crash

Some might say…… ;-)

RO is just a step weirder from their viewpoint.

Which leads to other points of emphasis – the icon bar and how a program is capable of running without something always being on screen, plus of course, the lack of implied pop to top, not polluting the screen with menus….