LinuxMCE Forums

General => Developers => Wiki => Topic started by: bongowongo on August 28, 2011, 02:38:09 pm

Title: Task | Identify structure of wiki | reqruiting / assessing
Post by: bongowongo on August 28, 2011, 02:38:09 pm
Is there any easy way to produce/view a hierarchical list of how the wiki is currently laid out? Or just a list of pages showing how the categories are organised? Just from the point of view of working out what needs doing and where.

Possy told me that the following page could give you somewhat of a hierarchy
http://wiki.linuxmce.org/index.php/Special:SpecialPages

Talking with Purps in a different topic about researching the structure of the wiki.
It is very important to understand how the linuxmce wiki is organized. I know that a lot of articles are inherited from Pluto. This makes information sometimes out of date, not catogorised properly, in the end it doesn't help to have a clear wiki.

After identifying the problems a task more further down the road woudl be to unify or standardize the pages
a helpfull link provided by Purps.

http://www.mythtv.org/wiki/MythTV:Manual_of_Style

This will be a complex task and will take longer to complete.



Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: purps on August 29, 2011, 02:47:04 am
I'm assuming we can't divide the wiki into separate sections for 710, 810, 1004 etc because a lot of information applies to all of them? I guess a tagging system that says what is relevant to what version similar to what we have now is the way forward there. definitely need to make that look nice though.

Sorry, going off topic there already. To be honest, I don't really have any feel for how the wiki is currently organised, nor do I have a feel for how it SHOULD be organised. I thought it was just a huge bunch of pages with the relevant categories written in there, and that some dictates what goes where. Where are the categories and sub-categories decided, is that the real question here?
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: twodogs on August 29, 2011, 05:16:42 am
I have not noticed much of any organization to the site. If I need to find something, I get completely out of the site and do a Google search "LinuxMCE telecom configuration" or something. Then I find a whole lot more than I could ever find in the wiki. A lot of the info and tutorials are alphabetical by title, which means if someone wants to find a tutorial about setting up a RAID, they must look under "C" for "Create RAID"

I think the front page of the wiki can be brought under control. Its when you start to drill down that the problems really get bad. So here is my suggestion:

Looking at the "Support" heading on the wiki front page, it seems to me that "Hardware" and "Troubleshooting" do not need to be there. I'd suggest that everything in those categories be moved to "Tutorials/Guides". Then we should really organize the "Tutorials/Guides" category. Lacking any better idea, why not organize it as it appears on the TV screen - Lights, Media, Climate, Security, Telecom, and Advanced? Then we might want to add "Hardware", and "Installation". If these titles need more info we could use parentheses, ie Lights (Home Automation). I think that all Hardware or Troubleshooting articles would fit nicely in those categories.

Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: DragonK on August 29, 2011, 08:22:04 am
why not organize it as it appears on the TV screen - Lights, Media, Climate, Security, Telecom, and Advanced?

For me This Sounds like a good idea.
Than it would be easier to find what your looking for.

Karel
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: Kezza on August 29, 2011, 08:31:58 am

I think the front page of the wiki can be brought under control. Its when you start to drill down that the problems really get bad. So here is my suggestion:

Looking at the "Support" heading on the wiki front page, it seems to me that "Hardware" and "Troubleshooting" do not need to be there. I'd suggest that everything in those categories be moved to "Tutorials/Guides". Then we should really organize the "Tutorials/Guides" category. Lacking any better idea, why not organize it as it appears on the TV screen - Lights, Media, Climate, Security, Telecom, and Advanced? Then we might want to add "Hardware", and "Installation". If these titles need more info we could use parentheses, ie Lights (Home Automation). I think that all Hardware or Troubleshooting articles would fit nicely in those categories.


I was thinking about this idea today but using the web admin breakdown as it expands the list a little more (such as irrigation and events along with network related info, power usage monitoring etc etc).

Either way I think it could be a good starting point to break the site down into manageable areas.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: purps on August 30, 2011, 10:19:42 am
Quote
why not organize it as it appears on the TV screen - Lights, Media, Climate, Security, Telecom, and Advanced?

I'm not sure it can be as simple as this, as many pages either won't be specific to any of them, or may apply to more than one. I tried to organise my user page in this way, and it made sense to a certain extent, but it was still difficult, and that was for a single setup.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: twodogs on August 30, 2011, 02:14:07 pm
Kezza suggested using the list from web admin as a start. That would give us something like the following:

Installation
A/V Eqipment
Media Directors
Orbiters
Lights
Climate
Irrigation
Security
Phone
General Serial Device
Scenarios
Events

Just like now, we could link articles in different categories. For instance, a Denon AV receiver would link to A/V Equipment and General Serial Devices
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: twodogs on August 30, 2011, 02:50:30 pm
OK, I'm just brainstorming here, but I came across an interesting site. It is a wiki about wikis, and I like the format as well as the content. The info on the left always lets the reader know exactly where he is, within the wiki. There are only three levels, so you don't have to drill down forever to find things.

http://wiki.customware.net/repository/display/wwyw/Chapter+01+-+Introduction

I don't know how hard this would be to set up, but maybe we could combine the users manual and wiki. The top level would be the official manual, then lower levels would be user submitted content. For instance, if I wanted to learn about lighting, I would click on "Lights" and read the manual. The second level would have subheadings for X10, Zwave, and Insteon. The third level would have articles on the devices.

This reminds me of college where I would always try to buy used textbooks. Not only would I get the authors content, but I would get all the notes scribbled by previous students.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: purps on August 30, 2011, 04:53:25 pm
OK, I'm just brainstorming here, but I came across an interesting site. It is a wiki about wikis, and I like the format as well as the content. The info on the left always lets the reader know exactly where he is, within the wiki. There are only three levels, so you don't have to drill down forever to find things.

http://wiki.customware.net/repository/display/wwyw/Chapter+01+-+Introduction

I don't know how hard this would be to set up, but maybe we could combine the users manual and wiki. The top level would be the official manual, then lower levels would be user submitted content. For instance, if I wanted to learn about lighting, I would click on "Lights" and read the manual. The second level would have subheadings for X10, Zwave, and Insteon. The third level would have articles on the devices.

This reminds me of college where I would always try to buy used textbooks. Not only would I get the authors content, but I would get all the notes scribbled by previous students.

This is just the kind of thing that I would want to see personally, but we'd have to think very carefully about the categories. I also think 3 levels should be the maximum, otherwise it would just get too convoluted.

With regards to that web admin list, that can't include everything, can it? I would have thought that would be a list of sub-categories, inside a "user manual" section for example. You would still then need other categories for "user pages", "hacks", etc, I dunno.

This was my attempt from another thread at generalising the wiki pages into sensible categories (not complete)...

-Hardware pages eg motherboards, z-wave device
-User pages
-Overview pages eg this is an MD, this is a core, the network must be set up like this because...
-Instructional pages eg the procedure for adding a light, NOT hacks
-hacks
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: bongowongo on August 30, 2011, 05:50:19 pm
This is just the kind of thing that I would want to see personally, but we'd have to think very carefully about the categories. I also think 3 levels should be the maximum, otherwise it would just get too convoluted.

With regards to that web admin list, that can't include everything, can it? I would have thought that would be a list of sub-categories, inside a "user manual" section for example. You would still then need other categories for "user pages", "hacks", etc, I dunno.

This was my attempt from another thread at generalising the wiki pages into sensible categories (not complete)...

-Hardware pages eg motherboards, z-wave device
-User pages
-Overview pages eg this is an MD, this is a core, the network must be set up like this because...
-Instructional pages eg the procedure for adding a light, NOT hacks
-hacks

I think the webadmin is very difficult to find stuff. So we can use it as a start, but I had troubles finding a lot of things at first.
I think the webadmin should also be rewritten, but that has of course nothing to do with the wiki
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: twodogs on August 30, 2011, 08:44:21 pm
It seems like we are starting to reach consensus on a general arrangement, but none of us are quite satisfied with the details. I agree that the list I posted (based on web admin) can be added to or even completely revised. I agree that if we come up with a really logical list, then that might serve as a basis for improving the web admin. I think that a wiki of three levels is a good number - any more and things get convoluted, any less and I think we'd have a category explosion.

Though we do not have the details ironed out, perhaps we are almost ready to make a start. If a particular branch of the wiki goes unfilled, then it is a candidate for removal. If a branch looks like it wants to go deeper than 3 levels, then we create another branch. It also shouldn't be too hard to rename branches after we get going.

However, it would be nice to start with the best outline we can think of. If we don't like the way the LMCE screen or web admin organize things, then maybe we have a few more days of brainstorming. I'll take everyone's notes from this thread, and come up with another option. I suggest we keep brainstorming until we have an 80% solution, then see if Bongo thinks we're ready to implement.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: twodogs on August 30, 2011, 10:25:46 pm
This is a first hack at the first and second levels of the new wiki. The third level would mainly be the articles themselves. I dug all over the wiki hardware and tutorials. I think most of the articles can fit into the following structure...



LMCE Installation Instructions (with pictures/videos)

LMCE Operation Instructions (with pictures/videos)

Core/Hybrid
 -Built systems (Dianemo, etc)
 -motherboards
 -video cards
 -TV capture
 -video capture
 -serial cards
 -network cards
 -sound cards
 -Raid

Media Directors
 - Built systems
 - Motherboards

Network
 -modems
 -routers
 -NAS

Control
 -Remotes
 -Orbiters (laptops, smart phones, VOIP phones, webpads)
 -Bluetooth
 -RS232
 -USB
 -IR

Media
 -Displays
 -DVD
 -MythTV
 -satellite boxes
 -cable boxes
 -Amps/Receivers
 -squeezbox

Automation (lights, climate, irrigation)
 -Aeon labs
 -Insteon
 -Zwave
 -X10
 -One-wire

Security
 -web cams
 -alarms

Telecom
 -Analog Telephone Adapters
 -VOIP phones

Scenarios/Events

User pages

Wiki Tutorial (Adding and Administering Content)
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: bongowongo on August 31, 2011, 12:01:25 am
All good input
I am very busy now. I will comment on everything end of this week/ weekend.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: purps on August 31, 2011, 10:43:39 am
twodogs, I think that is a really good first cut. I'm really coming round to this idea.

Pedantic point 1: TV capture, what about the homerun? It should go under network with "NAS" for example, but then you want to keep TV hardware together.
Pedantic point 2: Do you think there is a blur between "automation" and "security"?


Generally speaking, personally I was keen to separate the "information" from the "hacks", and with your structure they will all be lumped in together. I think the "hacks" do have a place contrary to what some may think, but it should be made clear that they ARE hacks.

Maybe this could be achieved using your structure, but having something at the top of the page that indicates this? Not unlike what we have now showing what version of LMCE the information is relevant to, maybe have an additional box saying "tested" or "recommended" or "hack" or whatever. I've decided I don't like the current system, as one can basically write whatever they want in there and it doesn't look structured. At the moment I envisage two columns, 1st being a list of the versions, and then for each one (in column 2) there should be A FEW pre-defined options for each one. The date and who added the information just isn't necessary.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: bongowongo on August 31, 2011, 12:07:07 pm
twodogs, I think that is a really good first cut. I'm really coming round to this idea.

Pedantic point 1: TV capture, what about the homerun? It should go under network with "NAS" for example, but then you want to keep TV hardware together.
Pedantic point 2: Do you think there is a blur between "automation" and "security"?


Generally speaking, personally I was keen to separate the "information" from the "hacks", and with your structure they will all be lumped in together. I think the "hacks" do have a place contrary to what some may think, but it should be made clear that they ARE hacks.

Maybe this could be achieved using your structure, but having something at the top of the page that indicates this? Not unlike what we have now showing what version of LMCE the information is relevant to, maybe have an additional box saying "tested" or "recommended" or "hack" or whatever. I've decided I don't like the current system, as one can basically write whatever they want in there and it doesn't look structured. At the moment I envisage two columns, 1st being a list of the versions, and then for each one (in column 2) there should be A FEW pre-defined options for each one. The date and who added the information just isn't necessary.

re: hacks

The problem with hacks is that they can get outdated very quickly and are usually not maintained. Also hacks in the forum are not in the wiki.
I see that they are very usefull, but on the other hand very confusing. I remember in my newbie days following wiki-hack page that was outdated and didn't work. It should not happen.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: purps on August 31, 2011, 02:27:44 pm
re: hacks

The problem with hacks is that they can get outdated very quickly and are usually not maintained. Also hacks in the forum are not in the wiki.
I see that they are very usefull, but on the other hand very confusing. I remember in my newbie days following wiki-hack page that was outdated and didn't work. It should not happen.

The reason I suggest it is because I would follow a wiki page and not know that it was a hack in the first place!! Then you find that it has bollocksed something up, you ask for help, and you're told "this is what happens when you try to hack the system!".

I appreciate they go out of date quickly, but surely that's part of what a "hack" is? I assume that on the main page we would have a little key explaining all these terms, and you would explain that any page displaying the "hack flag" may or may not ruin your life.

On the page itself, perhaps we are talking about 3 columns here; 1. for the LMCE version, 2. for the type of page (instruction, overview, hack) and 3. for the "bongo stamp of approval" or similar.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: twodogs on August 31, 2011, 03:51:26 pm
Quote
Pedantic point 1: TV capture, what about the homerun? It should go under network with "NAS" for example, but then you want to keep TV hardware together.
Pedantic point 2: Do you think there is a blur between "automation" and "security"?


Generally speaking, personally I was keen to separate the "information" from the "hacks", and with your structure they will all be lumped in together. I think the "hacks" do have a place contrary to what some may think, but it should be made clear that they ARE hacks.

Lets pretend that I insisted that the Homerun should go under TV, and you insisted that it appear under NAS We could put it in both places, just as current wiki articles can be set up to appear in "tutorials" and "hardware". But I suggest we avoid duplication if possible. It is a little difficult to find a perfect structure for this wiki, but it will be orders of magnitude better than the maze we now have (where it is easy to get lost). If we have a 3-level structure, and if the index is always present at the left of the screen, then it is almost impossible to get lost. For example, if someone looks for Homerun under "NAS", it takes only two clicks to either find it, or discover that it is not there. So they look at the index and know that it is probably under "Media->TV Capture". We would no longer have the hidden doors, secret passages, and one-way corridors that we currently have in the wiki.

I'm not sure exactly what you mean by hacks, or how many of them we have (an example might help me). Maybe hacks belong in the forum. Maybe they belong in the wiki mixed in with everything else, but are identified as hacks by font, page color, or some such.

Maybe automation and security should be lumped to begin with. If the category gets too big, we can split them out. But you're probably correct - not too many articles on security right now.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: purps on August 31, 2011, 04:27:31 pm
Lets pretend that I insisted that the Homerun should go under TV, and you insisted that it appear under NAS We could put it in both places, just as current wiki articles can be set up to appear in "tutorials" and "hardware". But I suggest we avoid duplication if possible. It is a little difficult to find a perfect structure for this wiki, but it will be orders of magnitude better than the maze we now have (where it is easy to get lost). If we have a 3-level structure, and if the index is always present at the left of the screen, then it is almost impossible to get lost. For example, if someone looks for Homerun under "NAS", it takes only two clicks to either find it, or discover that it is not there. So they look at the index and know that it is probably under "Media->TV Capture". We would no longer have the hidden doors, secret passages, and one-way corridors that we currently have in the wiki.

I'm not sure exactly what you mean by hacks, or how many of them we have (an example might help me). Maybe hacks belong in the forum. Maybe they belong in the wiki mixed in with everything else, but are identified as hacks by font, page color, or some such.

Maybe automation and security should be lumped to begin with. If the category gets too big, we can split them out. But you're probably correct - not too many articles on security right now.

Yes good points. They could indeed exist in two places, but it would be better not to. I suppose there won't be too many examples of this, so it could just go in both, then you find what you are looking for regardless of how you go about looking for it.

Regarding hacks, the first example that springs to mind is the HTTPS wiki page, which is now properly implemented http://wiki.linuxmce.org/index.php/HTTPS. Another would be the wiimote page http://wiki.linuxmce.org/index.php/Wiimote. Basically, if it isn't supported out of the box without some serious fettling, it's a hack as far as I am concerned, and this should be indicated so that people don't blame the system if it goes wrong.

I'm going to start another thread regarding page/version info, I would welcome your input.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: davegravy on August 31, 2011, 04:52:40 pm
This may be heresy, but keep in mind that I know very little about these systems:

Are there systems (other than wiki) that are better suited to LinuxMCE? I feel like what we need is a highly structured database-type organization of information, with a highly flexible front-end.

I'm brainstorming on the fly here, so bear with me.

It would be great if, for example, one could filter the list of receivers to show only those which are...

a) compatible, and
b) have ruby codes supporting discrete power on/off commands

...rather than having to click through each receiver, one at a time, and do this manually.

Or, it would be great if a user could identify themselves (set a preference somehow) as an 810 user, and automatically have articles/links to 710,1010, etc material filtered out.

Maybe what I'm describing is a custom web-documentation application? which would be too much work?


Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: nzlneil on September 01, 2011, 12:24:50 pm
Lets pretend that I insisted that the Homerun should go under TV, and you insisted that it appear under NAS We could put it in both places, just as current wiki articles can be set up to appear in "tutorials" and "hardware".
Yes good points. They could indeed exist in two places, but it would be better not to. I suppose there won't be too many examples of this, so it could just go in both, then you find what you are looking for regardless of how you go about looking for it.


Reading through this, it seems to me that we should have some sort of page tags to assist with grouping them together. This will allow for having one page that could be part of several systems.
e.g. "Some Brands Security System Model XYZ" could have the following tags (these are just some possible random ones off the top of my head, and are in no order)

Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: twodogs on September 01, 2011, 03:33:55 pm
We are beginning to gather a variety of different ideas - exactly as a brainstorming session should do. However, my thoughts are beginning to turn toward the practical. I'd like to know who is actually going to program the framework of our new wiki. What is his/her opinion of the technical difficulty of doing some of what we propose?
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: purps on September 02, 2011, 10:26:36 am
I'll try and mock something up this lunch time using collapsible tables, but dunno how that will look. Will look into other methods also for making it look more like the link you posted, twodogs.

I'm assuming it doesn't have to be a user-friendly method, as every page will go through a review process before it going into the main wiki? If so, that's another thing we need to think about - will the "approved" wiki pages be locked, so that new pages have to be created in a holding area or whatever before they are reviewed and introduced into the real thing?
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: bongowongo on September 02, 2011, 10:45:14 am
The holding pages, you can use the draft_pageX formula.
I think it is good if we can summarize this weekend, what ideas to go for and which on not.

Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: purps on September 02, 2011, 10:51:33 am
Once the new structure goes live, would it be possible to have any new pages automatically prefixed with "draft"? Because people won't necessarily know our methods, and might go ploughing in without following the right procedure.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: purps on September 02, 2011, 11:26:47 am
http://en.wikipedia.org/wiki/MediaWiki:Sidebar - how do we get those sexy little arrows in the side bar like that?
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: bongowongo on September 02, 2011, 12:06:32 pm
Once the new structure goes live, would it be possible to have any new pages automatically prefixed with "draft"? Because people won't necessarily know our methods, and might go ploughing in without following the right procedure.

We can lock certain pages maybe?
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: twodogs on September 02, 2011, 07:59:38 pm
Quote
I'm assuming it doesn't have to be a user-friendly method, as every page will go through a review process before it going into the main wiki? If so, that's another thing we need to think about - will the "approved" wiki pages be locked, so that new pages have to be created in a holding area or whatever before they are reviewed and introduced into the real thing?


Somewhere on the front page of the wiki, we should have a link called "Wiki Tutorial - Adding and Administering Content"

- In the "Adding Content" subheading, we would provide detailed instructions on how to create the perfect wiki article. We would have a link to the template everyone should use. We would give the authors the benefit of the doubt that they followed the rules, so there would be no holding area - a submitted article would immediately go up on the site.

- In the "Administering Content" subheading, we would have a table showing who is responsible for administering each major wiki chapter. Their first job would be move existing relevant articles into their chapter of the wiki. Administrators would periodically look at their wiki chapters for new content to make sure people are following the rules. If they found a problem they could fix it on the spot, get the author to fix it, or remove the article. If a particular chapter seems incomplete, an energetic administrator could go to the forums and request articles.



Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: Techstyle on September 04, 2011, 09:34:44 am
Been away for a few days, these are all good ideas:

I like the identification of hacks - but also would like a definition of 'hacks' as some newbie might not know what the pitfalls are with doing this.

We had talked previously about putting a tag in the wiki page that said the page was approved by the wiki team. Surely anything not approved by the wiki team falls into the early discussed draft group?

I do like the user identified when it comes to seeing if a particular page works. That way I can track the user down for more info if needed.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: bongowongo on September 04, 2011, 12:07:15 pm
Every page will make will first be a draft
e.g. draft_zwave
When it is finalized it will replace the page zwave, and the draft_zwave will become absolete and deleted.
Then the new zwave wiki page will be in a catagory approved/maintained by wiki workgroup.

My proposal is that for some key wiki pages not everybody can edit it anymore and should go through the wiki workgroup.
 
Hacks will need to get a disclaimer.

Everything not having a catagory is just not updated / visited / maintained by the wiki workgroup.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: posde on September 04, 2011, 12:27:24 pm
imho the pages that are maintained by the workgroup must still be editable by other people as well. The workgroup must make sure to do follow-up editing to make sure, the changes that occurred to a page are ok.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: bongowongo on September 04, 2011, 12:47:12 pm
imho the pages that are maintained by the workgroup must still be editable by other people as well. The workgroup must make sure to do follow-up editing to make sure, the changes that occurred to a page are ok.
So the wikigroup should review the changes afterwards, and make clear the rules how to edit a page.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: posde on September 04, 2011, 12:58:31 pm
Yes. That way you keep the initial reason for a wiki (community edits) alive and kicking while at the same time making sure things stay in order.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: nzlneil on September 05, 2011, 03:12:23 am
To assist the work group and allow them to keep an eye on the wiki pages, can a daily summary of updated pages be emailed to the people that are maintaining that group of pages with a list of pages that need a review? Once reviewed, the page can be approved, updated to correct format, or rolled back. This way users can update pages to correct and expand the page live, while the work group has the ability to review the changes to ensure that they conform.

Thinking out loud, could the email have an embedded a web page with the list of updated wiki pages in the body that gets it's information from a automatically updated page on the wiki, listing the page, and the status of that page. That way the reader can see at a glance if one of the other work group team has already reviewed the page, of if they need to review the page.

Email Body e.g.

Quote
Page       Status
zwave      Approved.
x10         Awaiting Review.
Telecom   Rolled back.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: posde on September 05, 2011, 04:51:27 pm
every user of the wiki can ask to get notified of changes in a page.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: purps on September 07, 2011, 12:48:50 am
This is a first hack at the first and second levels of the new wiki. The third level would mainly be the articles themselves. I dug all over the wiki hardware and tutorials. I think most of the articles can fit into the following structure...



LMCE Installation Instructions (with pictures/videos)

LMCE Operation Instructions (with pictures/videos)

Core/Hybrid
 -Built systems (Dianemo, etc)
 -motherboards
 -video cards
 -TV capture
 -video capture
 -serial cards
 -network cards
 -sound cards
 -Raid

Media Directors
 - Built systems
 - Motherboards

Network
 -modems
 -routers
 -NAS

Control
 -Remotes
 -Orbiters (laptops, smart phones, VOIP phones, webpads)
 -Bluetooth
 -RS232
 -USB
 -IR

Media
 -Displays
 -DVD
 -MythTV
 -satellite boxes
 -cable boxes
 -Amps/Receivers
 -squeezbox

Automation (lights, climate, irrigation)
 -Aeon labs
 -Insteon
 -Zwave
 -X10
 -One-wire

Security
 -web cams
 -alarms

Telecom
 -Analog Telephone Adapters
 -VOIP phones

Scenarios/Events

User pages

Wiki Tutorial (Adding and Administering Content)

Well having spent some time looking through the various pages at trying to put myself in the shoes of the new user, I am coming around to this method of organisation. I still believe it is important to identify the information as "approved" or "hack" etc, but this could be achieved using page "flags".

I think the "flag" system needs further discussion. At this moment in time I'm thinking three (SIMPLE) "flag" fields. One for the relevant version (710, 810 etc), one for the page status (eg reviewed, approved as per your suggestion nzlneil) and one for page type (instructional, overview, hack).

I would be interested in your views. One thing I will say - I think there need to be the bare MINIMUM of options for each of these fields, enough to cover the various situations, but not so many it becomes difficult to decide what option to choose.

Remember a draft version of what could be displayed is here http://wiki.linuxmce.org/index.php/Draft_Page_Status feel free to add your own ideas or just mention them here.

I assume these "flags" would only be editable by the wiki staff?
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: twodogs on September 07, 2011, 03:53:56 am
Quote
one for page type (instructional, overview, hack).

I would be interested in your views. One thing I will say - I think there need to be the bare MINIMUM of options for each of these fields

Agree that wiki contributors should have simple options from which to choose. Agree that hacks should be identified, but that doesn't necessarily mean we need another field. When we consider that a small percentage of wiki articles are hacks, and that hacks will be contributed by advanced users, then we might not want to make every Joebag'o'donuts wiki contributor fill out an extra field. Maybe we have two types of wiki templates - one for regular contributors, and one for hacks. The hack template could have a standard disclaimer at the top, be a different color, have different fonts, etc.

Also not sure we need to differentiate "instructional" from "overview".  The top level of each category would actually be the overview, then the instructional wiki articles would be in the second and third levels. For instance, when a newbie wants to install LMCE, said newbie clicks on "LMCE Installation Instructions" where he immediately sees something very much like the current "Quick Start Guide". http://wiki.linuxmce.org/index.php/QuickStart_Guide Much of this overview-type content would come from what is now the LMCE Manual. Only the administrators could modify it. If someone thought that the overview was inadequate, then they could submit their ideas to the chapter lead (or whatever we call them) instead of writing a wiki article. The second level of "LMCE Installation" would probably have a category called "Video Setup" among others. This would also have some video overview content along with access to third level articles like "black screen", "fonts too small" and such.

If the newbie is having a hard time getting his telecom gear to work during installation, he might decide to get really smart on the subject and could click entirely out of the "installation" chapter and into the "Telecom" chapter where there would be a good overview of the way telecom works in LMCE. With all his detailed questions answered, he could then return to the "LMCE Installation" chapter.

The overall concept is that we combine everything into a single source. Right now, if I want to learn about a subject I have to read the manual, then read the tutorials, then visit the hardware page, then read the forums, etc. And after doing all that, I do a Google search and find even more stuff! What I'm suggesting is one way to end all of that. All how-to content would fit into a 3-level wiki structure.
Here is a possible way forward, subject to the approval of Bongo and crowd.

edit: Actually, I suspect that once we start sorting we might find that the second wiki level will be mostly or all overview, and only the third level will have user-submitted articles.


Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: purps on September 07, 2011, 02:43:46 pm

Also not sure we need to differentiate "instructional" from "overview".  The top level of each category would actually be the overview, then the instructional wiki articles would be in the second and third levels.


What I meant by the "overview" page type is that it is informative i.e. it explains how the system works or just gives information generally. If you look at my draft page status page, so far I have...
-This page is for information
-This page is an instruction
-This page is a hack

I think that there is a place for this system, as it identifies what you are looking at exactly. I did think about these three terms in great detail to begin with, and now that I have thought about it some more, I will stand by them. I think that every page you find will fall into one or more of these categories and it immediately tells a new user what they can expect if they continue reading.

With regards to the other flags, would an "Approved" and "Awaiting review" suffice? And for the version, see my draft page, I think something like that is what we want.

Would the user be able to edit these flags, or would the wiki bods do all of this when they review the page? I'm leaning more towards the latter at the moment.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: twodogs on September 07, 2011, 03:04:26 pm
I had not seen your draft page in a while. I vote for the second status box with the yes/no format. As for the type of page, I assume the template would have the three options with instructions to remove two? Seems pretty easy to me.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: purps on September 07, 2011, 03:13:23 pm
That sounds good, then the options are in front of you to see, and you get rid of the ones that DON'T apply.

I've just had a little fiddle (ahem) during my lunch break, see what you think http://wiki.linuxmce.org/index.php/Draft_Page_Status
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: twodogs on September 07, 2011, 03:39:44 pm
Format looks good to me. However, the "awaiting review" and "confirmed" box brings up a potential problem. Do we have enough people, with enough skill, who are not devs, and who are willing to review all the wiki pages? I doubt that all of our "chapter lead" will have enough system knowledge to approve articles. Perhaps the best way to answer this is to give it a shot and see if the box gets filled out?
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: purps on September 07, 2011, 06:00:27 pm
Format looks good to me. However, the "awaiting review" and "confirmed" box brings up a potential issue. Do we have enough people, with enough skill, who are not devs, and who are willing to review all the wiki pages? I think I could volunteer for a chapter or two, if that meant organizing and clarifying the content. I don't think I'm enough of an expert on the system to approve articles.

I would hope so! Looking at the list of people that volunteered, I'm sure we could work it out amongst us. And if not, we can ask on IRC, here, or try it out ourselves. I imagine it would be a slog to begin with, but once it's all done, I would have thought that this would be relatively easy to keep on top of.

Besides, it's not just the technical stuff - it's the language and general "feel" of the pages that we'll also be moderating in order to keep everything consistent. It's all very well supplying a "this is how it should be done" page, but people aren't going to read all that when doing their wiki page. If they do, great, but I would have thought that mostly people will just want to scribble stuff down and leave the tarting up to us lot.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: nzlneil on September 09, 2011, 02:48:52 am
Looking at the draft page, I can see that there could be some confusion in pages where the page has both "This page is a hack" and "The content of this article is approved."

From a users POV, does this mean that the information on the page is an approved hack?

Thinking of the bigger picture, what actual purpose is a hack page for? I can only see 2 reasons for a hack page.

If a user is documenting how they got a piece of hardware to talk to the software, or documenting how they implemented a feature, I think marking the page as a "hack" does not sound right. Maybe marking it as a "Contributed How To" would be a better option.

Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: purps on September 09, 2011, 10:45:43 am
Yes, I hear what you are saying. Perhaps "approved" is the wrong choice of word. Maybe just "reviewed" and "not reviewed". I will try to address this possible confusion in the explanation as well.

And yes, perhaps "hack" is the wrong choice of word as well, it is a word that we chuck around amongst ourselves, but isn't necessarily "new user friendly". Maybe the word "workaround" would be more appropriate. I think your two explanations for what a hack/workaround is is bang on, I will incorporate this also into the explanation.

Whilst I don't want to make it sound like a negative thing, I do think it is important to convey to somebody reading the wiki that it is not in the spirit of things as it were; referring to your first point (fixing a bug), they should be filing a ticket or fixing it properly with the developers, not just fettling their own installation. Referring to your second point (implementing a feature), the same thing applies, they should be working with somebody to get the feature included properly.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: purps on September 09, 2011, 03:57:17 pm
OK I change the reviewed/not reviewed part, I think that looks better now.

I haven't changed the hack part yet, I am in two minds about this now. I would be interested in some other opinions!
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: mcefan on October 01, 2012, 07:02:28 am
Lets pretend that I insisted that the Homerun should go under TV, and you insisted that it appear under NAS We could put it in both places, just as current wiki articles can be set up to appear in "tutorials" and "hardware". But I suggest we avoid duplication if possible. ... If we have a 3-level structure, and if the index is always present at the left of the screen, then it is almost impossible to get lost.

There is a reason why shopping sites keep track of what you click on and make suggestions on what you should look at next, or what other people did following what you just did: thinking flows by association.
An article should be in as may categories at necessary.

If I just completed my install, it's just natural for me to wonder "what else" I should install before leaving the installation phase.


http://en.wikipedia.org/wiki/MediaWiki:Sidebar - how do we get those sexy little arrows in the side bar like that?
By installing the extension. Please note that extensions are version specific.


Somewhere on the front page of the wiki, we should have a link called "Wiki Tutorial - Adding and Administering Content"

- In the "Adding Content" subheading, we would provide detailed instructions on how to create the perfect wiki article. We would have a link to the template everyone should use. We would give the authors the benefit of the doubt that they followed the rules, so there would be no holding area - a submitted article would immediately go up on the site.

- In the "Administering Content" subheading, we would have a table showing who is responsible for administering each major wiki chapter. Their first job would be move existing relevant articles into their chapter of the wiki. Administrators would periodically look at their wiki chapters for new content to make sure people are following the rules. If they found a problem they could fix it on the spot, get the author to fix it, or remove the article. If a particular chapter seems incomplete, an energetic administrator could go to the forums and request articles.

I added a few pages that that address some of the above needs. Please see the section title "Ongoing" on my user page: http://wiki.linuxmce.org/index.php/User:Mcefan#Ongoing

I do like the user identified when it comes to seeing if a particular page works. That way I can track the user down for more info if needed.

Make the "discussion" tab of a page the standard communication medium for pages maybe?


To assist the work group and allow them to keep an eye on the wiki pages, can a daily summary of updated pages be emailed to the people that are maintaining that group of pages with a list of pages that need a review?

That is the function of the "recent changes" special page: http://wiki.linuxmce.org/index.php/Special:RecentChanges
It can be filtered, but it's still labor intensive though, not automated.
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: bongowongo on October 01, 2012, 02:26:13 pm
There is a reason why shopping sites keep track of what you click on and make suggestions on what you should look at next, or what other people did following what you just did: thinking flows by association.
An article should be in as may categories at necessary.

If I just completed my install, it's just natural for me to wonder "what else" I should install before leaving the installation phase.

By installing the extension. Please note that extensions are version specific.

I added a few pages that that address some of the above needs. Please see the section title "Ongoing" on my user page: http://wiki.linuxmce.org/index.php/User:Mcefan#Ongoing

Make the "discussion" tab of a page the standard communication medium for pages maybe?


That is the function of the "recent changes" special page: http://wiki.linuxmce.org/index.php/Special:RecentChanges
It can be filtered, but it's still labor intensive though, not automated.

Thanks for you insight and points of view
So where do you want to start? What is the best approach?
Title: Re: Task | Identify structure of wiki | reqruiting / assessing
Post by: mcefan on October 01, 2012, 05:06:01 pm
So where do you want to start?
I already started. I'm not for discussing things at infinitum. The rubber has to meet the road somewhere, and people have been complaining for too long. Whatever I can do while I'm reading, I will do, keeping in line with the decisions that have been made in the discussions (whenever they exist).
The problem I have is that I've just been around 2 weeks, so I do not know
enough yet. All I know is that learning has been extremely difficult, and that's highly abnormal for me because I learn fast ad read a lot. So I just decided to do something about the problem.
I actually started before even knowing that others were at it, because I could not even find that. I keep stumbling on things here and there in a disorganized fashion (lots of reading, good note taking, and luck). As I find things, I place them where they could easily be found, so others can contribute (at first, I thought it was not possible - that needs to be fixed). It was not CLEAR from the initial contact in the environment (something to remedy).

That said, I started with the ability to find things because that seems to be the biggest hurtle. Cosmetics matter, but "substance you can not find" is a game stopper. The most important thing for me at this time is the structure of the categories (the table of contents of the site). I did my best to read all previous discussions and comments I could find, and summarized them on my  user page. Please take a look.
twodogs 's suggestion needs to be implemented (http://forum.linuxmce.org/index.php/topic,11910.msg83542.html#msg83542) along with purps' suggestion (http://forum.linuxmce.org/index.php/topic,11910.msg83767.html#msg83767). This is desperate, we need to start something. Adjusting later will just be a matter of recategorizing a few articles (which should be an ongoing task anyway).
Right now, we need to be able to find things if they exist, and group them. At least, if they're not relevant to the user, they are all grouped and he/she can move on to the next one. That's not to say that they should not be flagged as suggested.
The categorization is crucial, and people must clearly see their options (other articles related to the same thing).

So, to answer your question: grouping the articles (categories).

The existing instructions are here: http://wiki.linuxmce.org/index.php/Help:Editing_advanced#Placing_a_document_in_the_table_of_contents
We need to edit them.

What is the best approach?

Finalize twodogs 's suggestion (http://forum.linuxmce.org/index.php/topic,11910.msg83542.html#msg83542) and start moving the articles. Each person can be assigned articles starting within an alphabetical range (for example: I could take care of F-J).
Please read the page I wrote about Article categories (http://wiki.linuxmce.org/index.php/Help:Article_categories#Choosing_the_order_in_which_a_page_is_positioned_in_the_category.27s_listing), it explains how to position them in the list.
Also read the classification worksheet for some ideas of how to chose the labels of the categories: http://wiki.linuxmce.org/index.php/Help:Classification_worksheet.

Once they are grouped, we can assign people to standardize the content, each person being in charge of a section of a top level category.