Documentation - The Style Guide

Having raised this issue by email with Castle & ROOL, it was suggested a few weeks back that I bring it up here when the forums were up and running again. Unfortunately, I’ve only just noticed that’s now happened. :-)

I think The Style Guide is in need of an overhaul; there are areas where it is clearly out of date (for example user choices) and there are areas it doesn’t cover (for example toolbars). There will no doubt be many others if it’s scrutinized carefully – and it’s possible that some areas could simply be improved.

I also think it needs to be published online so that it’s available to everyone without going to the lengths of purchasing the C tools. This would be beneficial to the OS as a whole because it would mean people who program in BASIC or use GCC - people who might not have a copy if they’ve not bought the C Tools (or, previously, the PRMs and who rely on the StrongHelp equivalent) – would be able to access it and adhere more closely to it.

The Wiki can be used for such documentation, though it’s not very good with images at the moment.

Who has the copyright? Can it be published online? Is it available in electronic form?

Who has the copyright? Can it be published online? Is it available in electronic form?

Almost certainly the copyright is the same as the PRM’s, ie Castle (I think)

It’s included on the C/C++ Tools as a PDF file, the same as the PRMs.

Whether the source for that is available is the question – but if not, the text and images can be extracted from the PDF file. (Though, while updating it, the images could do with a bit of updating, I think – all windows and menus are displayed with the system font, for example).

For this sort of documentation, in the style of a manual, I think it would be sensible to store and edit the text in a format which can be rendered as either a PDF ‘book’ for printing and in HTML for online viewing. That way, there is only one central source.

To public the PRMs and the style guide is a very good idea as it may be a good idea to public commented code examples written in C/C++ or BBC BASIC as Microsoft do on MSDN. I believe that information about a technology are always very helpful into “spread” the technology itself, and yes I have the C/C++ suite from Castle and all the manuals are in PDF format there.

For this sort of documentation, in the style of a manual, I think it would be sensible to store and edit the text in a format which can be rendered as either a PDF ‘book’ for printing and in HTML for online viewing. That way, there is only one central source.

It could be simplified still, and just published online in PDF format. Static HTML pages, generated from the same source would be fine, of course – but it’s not a necessity if a PDF file can do the job.

For discussing changes to be made to it, either the forums or the mailing list I originally set up could be used, but publishing it in a way that allows meaningless changes to be made by anyone is probably not so good. I did originally think a wiki was ideal, but as this example shows (or it will if I’ve followed the instructions correctly!) it might not be so wise.

I did originally think a wiki was ideal, but as this example shows I don’t see a problem with your example. After all, the current version shows what you want. The problem with the page is there’s not much content! ;)

I think it would be great to upload the whole Style Guide to a wiki and let people tinker away…

Adam

I don’t see a problem with your example. After all, the current version shows what you want.

Yes, but only because I happened to look at the page and spot the wish list style comment at the bottom. On a simple bit of text like that, its easy to see – but that might not always be the case.

The problem with the page is there’s not much content! ;)

Quite. Feel free to add some. :)

I originally set that page up as a possible location when I first considered a wiki as a good solution, and was willing (as I said in my email first to Castle, and then to both Castle and ROOL) to do the necessary work to get the Guide online in that format, if I had permission.

At that point, I didn’t realise there was also a wiki on this site – if I had done, my suggestion at that time would have been to put it here.

However, while I’m now less convinced that a wiki is such an ideal solution for the guide itself, I think that page makes sense as a page about the guide.

Personally, while I would like to see things like PRMs or style guide material on the ROOL Wiki (subject to relevant permission from whoever owns the original documentation), I don’t see a problem with it appearing somewhere else either. Whatever the community prefers is by default the best route. We can always bung a page into the ROOL Wiki to link to documentation hosted elsewhere. In the long term, if the external site was being taken down, the documentation could always be migrated elsewhere; either here, or some other external location.

IMHO we ought to give some careful thought to the most appropriate master format for documents, though, with an eye to ease of editing combined with future proofing.

I’ve finally got around to logging into the forums again after almost a year… woo!

Personally, while I would like to see things like PRMs or style guide material on the ROOL Wiki (subject to relevant permission from whoever owns the original documentation), I don’t see a problem with it appearing somewhere else either.

Top stuff. Did we ever find out the position on whether the Style Guide can looked at/updated/shared/published etc, or not? The only response I ever had from John Ballance was that “no decision has been made”

My current position is that I’m very busy up until Wakefield (and probably for a month or so after) – primarily with WebChange, which I want to bring up to a releasable state by the show. Other than that, the only programming project I’m commited to is an invoicing program (actually four, but I intend to use a single back-end with bolt-on front-ends for each client – and I’m going to write in in BBC BASIC, so I can do some of the work on RISC OS), and I’m keeping the accounts stuff to just my current batch of regulars.

The upshot of all this is if I’m going to spend any time on the Style Guide – at least initially extracting the existing text and putting it into a suitable format ready for discussion/possible improvements, as I originally wanted to do – then now is the time for a decision to be made.

(With an obvious question – what format is it in already, and can this be used as a starting point instead of the PDF?)

In fact, when I do have a little time, I might just press on and extract the text and file it away somewhere in a suitable format in readiness for an answer, but not online, obviously. If/when I do this, I could always hand it over to you guys and then we can think about making any decisions. (Perhaps seeing something productive might help in making a decision!)

IMHO we ought to give some careful thought to the most appropriate master format for documents, though, with an eye to ease of editing combined with future proofing.

If/when I do anything, unless anyone comes up with a better solution, I’ll probably go with Ovation Pro – because I can then work on whichever machine I’m using (though I need to upgrade the version I had on RISC OS, and buy the Windows version!); exporting as PDF is as simple as printing, and I believe there’s a HTML converter around somewhere (and if not, I could probably come up with a WebChange script – when that’s finished!).

Please NOT in Ovation Pro, or any nontextual format. Once original content is mixed with formatting it is “as lost as the eggs in a cake”. In order to comment on a document, say correct spelling, grammar or punctuation, it is necessary to quote the offending text and display the suggested replacement. Referring to such and such a sentence 4 lines into paragraph such and such is a no-brainer. I have had lots of experience guiding authors of books, and, believe me, plain ASCII for all original content is vital if it is to be possible to add comments or suggestions for change. I do not have Ovation Pro, or Impression, but even if I had I would not advise their formats for material that is to be edited. TeX or LaTeX source is not so bad, because it is at least text, so long as material is not concealed in macros. For heaven’s sake keep content and layout separate. The layout can come later – you could have a beauty contest between sample pages – but for the text itself, plain ASCII please.

I tend to agree with the comment above re text.

Vince, if you do get started on this, I’d be happy to help out. I’m interested in the Style Guide issue, and have experience of editing and proofreading.

I don’t think I’ve ever been asked to proofread plain text, so I’ll have to take your word for it that it’s a better method. Everything I’ve ever done has been in printed form, on which I can make notes, or PDF, for which I make separate notes in a text file to send back to the source – both of which include formatting and styles. I’ve never found it a problem referencing what the corrections/suggestions relate to, which are as likely to be pointing out a wrong cross referenced page, or the wrong image, as they are a spelling or grammar mistake, and in those cases plain text is considerably less useful.

It’s worth noting that as far as basic proofreading (spelling, grammar, punctuation) is concerned, for those who prefer plain text, that plain text can still be extracted from Ovation Pro documents, just as easily as it can be from PDF or any other format.

However, I’m not really suggesting Ovation Pro as a ‘final solution’ – to be totally honest, I don’t really care what format it ultimately ends up in, just so long as it’s done, made current and thereafter kept current. Ovation Pro would be an interim solution, and a practical one for me because I’m familiar with it, albeit somewhat rusty (I’m more familiar with OpenOffice now, having been using that for some years for practical reasons, but suggested Ovation Pro because it also runs on RISC OS).

Getting it initially into plain text is a piece of the cake (litterally a matter of seconds – I’ve just done it) – in which, while the eggs might not be lost, the flour is: it’s littered with non-ASCII codes, it’s hard to see at a glance where headings are, and so on. It shouldn’t take an unbearably long time to sort that out, though, especially if I look at it here and there between other tasks.

Regardless of all that, though, no matter what I do at this stage, nothing can be done that involves it leaving my hard drive until the copyright holders say “yes, this can be done as part of the RISC OS Open work…”

I agree that, if the margins are wide enough, paper is the easiest medium for inserting amendments. But that can use an awful lot of paper. Vince, if you use StrongED, and a recent version of it, here is a tip you might find useful. Load in your document, then change mode to News. You will see an icon at the far right of the smarticon bar of a little face peering up at a pair of scissors hovering over his pate; “a little off the top, sir?” is what you should be imagining. Click the icon and all top-bit-set characters will be replaced by spaces, and also all control characters apart from newlines.

I do use StrongED – and that’s one (of many, probably) handy little features I didn’t know about. I’m not sure if it’s the best solution here, though, because some of the top-bit-set characters might be better replaced with ASCII characters that most closely match them – so better handled by search and replace.

Getting it initially into plain text is a piece of the cake (litterally a matter of seconds – I’ve just done it) – in which, while the eggs might not be lost, the flour is: it’s littered with non-ASCII codes, it’s hard to see at a glance where headings are, and so on. It shouldn’t take an unbearably long time to sort that out, though, especially if I look at it here and there between other tasks.

In fact, when I extracted the text before I did so the wrong way. Having now done it again, the result is a tidy text file – which I can’t really do anything with because AFAIK no decision has been made by JB et al.

(Internally, I can do things – when I have a few minutes here and there, I’ll start noting areas that need addressing/updating/adding, ready for when this can be looked at properly).

I think the best place to keep it would be a wiki. That would give us good team work tools and integrated diff. Most big open source projects seem to keep their documentation in wikis now, which works quite well.

A wiki would make sense, though it’d need some work on the ROOL wiki to make it suitable (there’s no history log, diff or preview function AFAICS). It’d be better to fix the ROOL wiki, but as in interim I’m sure riscos.info could host it if the licence allowed (there’s already been some preliminary work done on Style Guide changes there too).

I’m not convinced wiki formatting is good though – it doesn’t really help with printing/PDF conversion – and wiki navigation is poor (much of my PRM reading is from end-to-end of a chapter which isn’t easy in a wiki unless it’s one big page). There’s wikitex but it’s only really for equations and figures, not page layout. Possibly use a wiki to write Latex and then some sort of handle-turning to produce an output PDF? But then Latex doesn’t convert to web too well.

Maybe these might be work looking at: http://latexki.nomeata.de/index.html http://www.inf.ed.ac.uk/undergraduate/projects/erikmcclements/

RISCOS Ltd seem to have gone the route of XML documents with separate converters for web or PDF, which might be a route to follow.

Out of interest, what did Acorn use for preparing the PRMs? Was it something like Quark or FrameMaker? The PRMs were around before RISC OS DTP was, though I’ve seen some later documents in Impression (DCI4 spec and an application note published by ARM).

FrameMaker. The HTML output from that was terrible. It scaled down all the images without any kind of subsampling, so they looked truly terrible. I remember spending a looong time redoing a bunch of the images via ChangeFSI for the J233 RiscPC.

Ah, thanks. That would explain the mess that was the HTML version of the VIDC20 datasheet.

"[…]only double-click on it when I want to use it. It’s annoying the way it just plonks itself on the iconbar and doesn’t open its window. Could this be made an option in the choices, perhaps?"

I’d like to see such recommendations on functionality included in any revised Style Guide, along with the Help system too (or a development of it). What else should be standardised?

What else should be standardised?

Recently I was observing how different applications cope with providing large amounts of options in a reasonably small window. Some use Rik Griffin’s Tabs Toolbox gadget, others use a series of radio buttons to achieve a similar tabbed design. And there are a couple of other methods I remember noticing at the time which escape my memory now.

I think it would be helpful to standardise this, and standardise the position of the radio buttons if that method came out on top. I’ve seen them on both the left- and right-hand side. Don’t remember ever seeing them being used horizontally.

The Tabs method is obviously more familiar to non-RISC OS users, and Rik’s done a great job of implementing it, but the radio button method is arguably more “RISC OS”, and equally nice and tidy, IMHO.

Rik Griffin’s Tabs Toolbox gadget, others use a series of radio buttons

Good point – maybe ConfiX is one of the others you’re thinking of.

radio buttons […] on both the left- and right-hand side.

On the left could seem a more logical decision, i.e. reading left to right. But if option panes have submenus etc. to select from, these will generally be to the right of those windows. Therefore, placing radio buttons (or tabbed icons, if that’s a proposed method) further to the right would result in a shorter distance being moved by the pointer, if navigating a number of different tabs/selecting from menus.

Don’t remember ever seeing them being used horizontally.

This could be a bit clumsy with different length strings, formatting widths, spacing between radio buttons, etc. but someone could probably prove this not to be an issue. (Such issues irrelevant if icons used.)