Wiki categories

So, it looks like the new wiki supports placing pages into categories. But what categories should we use? I think it would be a good idea to start off with categories that match the sections linked to by the main index page:

• CortexA8 – For pages in the Cortex-A8 port section
• HAL – For all pages in the HAL section.
• Specifications – For pages in the Individual specifications section, and any other specifications that should probably be linked from there.
• PRMs – For all pages in the PRMs section.
• Software (or SoftwareInfo)? – For pages in the Software Information section
• StyleGuide – For the pages in the Style Guide section.
• SourceCode – Everything related to getting and building the RISC OS source code. Guides for CVS access, using !Builder, understanding the source tree, etc. Basically what’s in the Technical notes section.
• Diary – For pages in the RISC OS Diary section
• Roadmap – For pages in the RISC OS Roadmap section
• BugReporting – For pages in the Debugging crashes section
• FAQs – For FAQ pages
• Help – For website help
• Other – For other stuff like merchandise ideas

Then ontop of that, we could add a few new categories:

• Debugging – A new section to help give programmers advice on how to debug things
• Porting – Advice on porting RISC OS
• Proposals – For proposals/specifications of things that haven’t yet been implemented.
• UserGuide – For a new RISC OS User’s Guide, should we ever get round to writing it
• Modules – The main page for any module should be in this category, thus providing an index of all the documented modules
• Commands (or *Commands if the wiki allows it), SWIs, Vectors, Events, ServiceCalls, UpCalls, WimpMessages, etc. – Indexes for all the main types of OS API.
• Toolchain – Documentation for the C/C++ tools
• FileSystems – For a list of all filing systems, and all filing system-related pages
• Users – For any pages that people make about themselves
• WIP – For any pages that are a work-in-progress in some way

Any other categories that people can think of?

Any other categories that people can think of?

• Tests – For pages that will enable people to test the wiki without unneccesarily adding to the changelogs of legitimate pages (come to think of it, is there a sandbox facility available?)

• DeleteMe – For pages that are no longer needed/were created by mistake and should be removed/ignored.

Some thoughts:

• I think we may be defining categories in too fine-grained a manner. It’s a quite simple grouping mechanism and we’ve already listed well over 20 different proposed categories. My finger-in-the-air guess is that we should try to keep this to less than 10. The “Help” category I recently introduced on the Wiki is only there as an example and does not necessarily have to be kept.

• Having experimented a bit with them, it turns out category names can have spaces in, which makes them easier to read.

I’ve just been updating a few things on the Wiki (see here for details) and in passing put any specifications I found under category “Specification”. This means we now have:

• Help
• Specification

I can see how “Delete Me” could be handy too. As for the rest, how about we boil it down thus:

SourceCode – Everything related to getting and building the RISC OS source code. Guides for CVS access, using !Builder, understanding the source tree, etc. Basically what’s in the Technical notes section.
BugReporting – For pages in the Debugging crashes section
Debugging – A new section to help give programmers advice on how to debug things
Porting – Advice on porting RISC OS

“Guide”

FAQs – For FAQ pages

“Help” (alongside the Web help stuff), or in “Guide” if a FAQ is related to a Guide.

PRMs – For all pages in the PRMs section.
StyleGuide – For the pages in the Style Guide section.

“Reference”

Commands (or *Commands if the wiki allows it), SWIs, Vectors, Events, ServiceCalls, UpCalls, WimpMessages, etc. – Indexes for all the main types of OS API.

I think that should fall under the PRMs, i.e. “Reference” (probably by default).

UserGuide – For a new RISC OS User’s Guide, should we ever get round to writing it
Toolchain – Documentation for the C/C++ tools

“Manual”. “Operation Manual” or “User Manual” might be better but I think that’s too long for people to be bothered typing it out and spelling errors may be more likely. Hopefully, the shorthand won’t cause confusion with “Guide”.

Proposals – For proposals/specifications of things that haven’t yet been implemented.

“Proposal”; agreed, because this indicates that discussion or revision may be more active so being able to more quickly find such pages via a categorised grouping would make a lot of sense.

Modules – The main page for any module should be in this category, thus providing an index of all the documented modules
FileSystems – For a list of all filing systems, and all filing system-related pages

I’m on the fence. I can see how the documented modules might be handy, though this probably collides with Software Information pages for individually released modules. At the same time, that sort of stuff should probably be folded into the PRMs and end up under “Reference”. Is it right to single out file systems? I’m not so sure it is; having all file system stuff listed in the filing system section of the PRMs might make more sense. Still, it could go either way. BTW, It’d be “Module” and “Filing System” – category names would be singular, since you’re describing a particular page. It makes more sense in the context of reading a page that way around IMHO.

CortexA8 – For pages in the Cortex-A8 port section
HAL – For all pages in the HAL section.

Well you’re biased Jeffrey :-) so I can see why you’d want those in their own category. Stepping back, though, is it wise to single out the Cortex A8 specific stuff in that way, or the HAL specific stuff? At least for the HAL, should that not fall under a PRM “Reference” section as well as being adequately linked from the Home page as well as the porting “Guide” category page(s)?

Diary – For pages in the RISC OS Diary section
Roadmap – For pages in the RISC OS Roadmap section
Software (or SoftwareInfo)? – For pages in the Software Information section
Users – For any pages that people make about themselves
WIP – For any pages that are a work-in
Other – For other stuff like merchandise ideas

I don’t really think these need to be categorised at all. They just seem to fall under ‘everything else’.

Summary of the above:

• Delete Me – unwanted
• Help – includes any general miscellaneous FAQ
• Specification – formal individual specification; invites folding back into PRMs eventually
• Guide – informal “how to”
• Manual – formal user guides for software or hardware systems
• Proposal – informal live proposal, subject to ongoing change and discussion
• Reference – formal reference documentation

Possibly:

• Module
• Filing System
• Cortex A8
• HAL

Modules – The main page for any module should be in this category, thus providing an index of all the documented modules
FileSystems – For a list of all filing systems, and all filing system-related pages

I’m on the fence. I can see how the documented modules might be handy, though this probably collides with Software Information pages for individually released modules. At the same time, that sort of stuff should probably be folded into the PRMs and end up under ‘Reference’.

You do know pages can be assigned to multiple categories, right? So these pages can be in both the Reference category and the Modules and/or FileSystems categories.

Stepping back, though, is it wise to single out the Cortex A8 specific stuff in that way, or the HAL specific stuff?

Perhaps, perhaps not… but as you can probably guess I’m under the opinion that more categories are better than few :)

At least for the HAL, should that not fall under a PRM section as well as being adequately linked from the Home page as well as the porting “Guide” category page(s)?

One of the issues with the HAL is that half of it’s “private” (i.e. for OS use only) while the other half is “public”. I think a distinction needs to be made in the way the documentation is structured, just so that application developers aren’t tempted to try using private APIs in their programs. Similarly we could add loads of other low-level OS documentation to the wiki, which is of interest to OS developers but shouldn’t ever be used by application developers.

I don’t know if it belongs in the wiki but ‘How to submit changes’ should be a lot more prominent than it is at the moment – I’d put it on the Home page.

You do know pages can be assigned to multiple categories, right? So these pages can be in both the Reference category and the Modules and/or FileSystems categories.

Yes. I’m talking about whether or not we have more fine-grained categories.

you can probably guess I’m under the opinion that more categories are better than few :)

Yes, from your original list. But as I suggested, I think it ought to be more around the 10 mark, roughly. The way categories are handled within the Wiki is crude at best. They could be a useful tool, but only if we keep a close eye on the way that they’re used. Eventually, someone will start asking for categories of categories (i.e. a hierarchy) – then you know we’ve really screwed it up.

While it’s true that pages can appear in multiple categories, the greater the number of narrower categories that we have and the more that pages naturally fit into several, the greater the chance of a page author having a different idea of what categor(y|ies) they should use compared to a reader, who’s then struggling to find the thing they want. I reckon having fewer, broader categories makes it less likely that mis-categorisation will occur.

With so many pages already in the Wiki, we also need to bear in mind that the majority of them are unlikely to end up placed in any category at all. I think I’d rather see people spend time improving the page content than mind numbing hours adding category declarations to the existing backlog of material.

All this said: This should probably be a majority rule issue, so right now we’ve only got 1 vote either way from you and I. Have to wait and see if anyone else weighs in with an opinion.

I think two and half years is long enough to wait before unsticking this :-P