Documentation / Wiki overhaul

[wierdbeard65]

First up, I don't want anyone to think I'm having a dig or complaining for the sake of it. I am not starting this thread in an attempt to start a flame war or invite abuse from anyone who is feeling a tad sensitive!

I have seen various comments over the weeks (months) that I have been actively monitoring thse forums which say three things:-

1) I'd LOVE to help out more, but I'm not a developer, so I don't see how I can.
2) The documentation / wiki is less than user-friendly (usually after someone has asked a perfectly reasonable question and been told "it's in the wiki")
3) "I'm a new user, can you tell me...." (Often resulting in an impatient "do your research on the Wiki then come back....")

Like most systems that grow organically (look at most corporate shared document areas!) the Wiki has become difficult for anyone unfamiliar with it's structure to use. Of course, those of you that have been here for a long time know where to find stuff and it isn't a problem, but please put yourself in the shoes of us lessar experienced members for a moment.

If I start at the home page for MCE, I see a friendly menu titled "Wiki / Documentation ". Under here are some links, so as a regular, impatient sort of person, I click on "Quick Start" which tells me how to install the software... HOLD ON, I have no hardware yet. Ah! Let's follow the link to "Architecture Intro". This starts with

The Core

The Core has no user interface other than an administration page (unless it is a hybrid).

Unless it's a WHAT??? Maybe I need to be less impatient, so back and try "Main / Table of Contents". Hummm. Now what? Scroll down and there's promising looking sections entitled things like "Tutorials", but the indexing is not well laid out, often with what seem to arbitrary sub-sections. You get the idea.

May I suggest that (assuming anyone is still reading this) someone who falls into the "I'd love to help" category takes on the task of overhauling the Wiki? The information that is there is fantastic, but what use is that information if it can't be found? Even the search feature doesn't neccessarily help unless you know the term to search for!

Personally, I'd like to see a "OK so you're sold, you have nothing, now what" guide for idiots. There was an excellent posting on a forum recently (and my apologies to the poster as I can't recall who you were or what the thread topic was, but I did congartulate you at the time, ptobably Thom or Andrew) which described the questions you need to ask yourself and how that influences the decisions you make about your setup.

Like I said at the start, no offense is intended, particularly to whoever it was that set the Wiki up in the first place, but can we have some structure, please?

I would offer to do this myself, but I don't have my system built yet and so it really would be the "blind leading the blind".

[logrus]

I would offer to do this myself, but I don't have my system built yet and so it really would be the "blind leading the blind".

Sounds like a perfect way to start if you ask me. You'll know what questions to ask if nothing else.

And I completely agree with you, the wiki needs some lovin'.

Cheers,
Tor Magnus

[wierdbeard65]

Sounds like a perfect way to start if you ask me.

Oh no, at least not yet! 

I intend to create my own "user setup" page and keep careful notes. Then, if nobody else does it, I'll have a crack.

Personally, I think one of the experienced system integrators would be the best person to do this. They know where to start a new project and the various paths it can follow. My attempts would be too biased towards what I did and would alienate anyone taking a different path (for example, even the question "Dedicated core or Hybrid" throws up a lot of subsequent options, requirements and considerations).

[colinjones]

You are right, it could do with some overhaul, and the "organic" comment is definitely valid. It is an issue of finding person-power, expertise and time.... Moreover, a full taxonomical analysis needs to be done, to "true up" the structure, organisation, and categorisation of articles to make things easier to find.

On the up side, you will be happy to know, that in recent months there have been movements to put some more structure around how development is done, planning, release management, and so on. This is something that hopefully will continue to "crystalise" as the effort becomes more systematic and professional. It is unsurprising that whilst there is still a critical shortage of resources like devs, there has definitely been new blood adding to the pool. So the aforementioned crystalisation is not entirely a coincidence!

Certainly, I recently started to put together the skeleton for an "all singing, all dancing" installation troubleshooting guide.... I haven't yet started fleshing it out, but have the reference points. There are several other "mega guides" that could easily be written, like "hardware selection guide", etc that arranged into an Introduction Pack from the main page would probably help out a great deal....

We do need volunteers to get the wiki into better (and more logical) shape.... if there are any experienced wiki authors out there, please set forward!

[wierdbeard65]

Thanks, Colin!

It's good to know that I am not alone in being lost and that someone is out there looking for me! I think that in the long run it would be a valuable investment. Better docs lead to fewer questions which lead to less wasted time from the Devs (and anoyance to boot!)

As I'm neither and experienced Wiki author nor MCE user / implimentor, I'm really not the right person to do this, although as I said earlier, I'd be happy to do it if nobosy else steps up to the plate (just not yet!!!!)

I shall wait with baited breath for the aforementioned guides.

[Pnuts]

I'll gladly help do a revamp. I've been updating and adding pages as I have gone so far. I am just a novice on the Wiki scene, but its a good time to learn.

My most notable contribution so far was the Z-Wave getting started guide: http://wiki.linuxmce.org/index.php/Z-Wave_Getting_Started which is by no means complete in any way.

We probably need someone to gather a list of volunteers and start assigning pages to be updated. We might also want to create a template to follow when updating the pages to create a good symmetry for future readers\browsers and keep everything coherent as more hands get into the pot.

[alx9r]

I'll certainly contribute as long as there is an agreed-upon plan and structure in place for wiki improvement.  I do have some wiki experience and have had a LinuxMCE system for about a year.

Alex

[hari]

many ppl were requesting wiki reworks in the past, but unfortunately nobody cared to do the real work.

[wierdbeard65]

I'm not sure the pages themselves necessarily need updating, although I did suggest elsewhere that as pages get edited, a grid be added to each indicating which version(s) of MCE the page applies to / has been tested with. This is going to be particularly important with the release of 8.10.

What does need an overhaul (IMHO) is the start page and the immediate sub-pages (particularly the tutorials menu). It needs to be much easier to burrow down to what you need to know, if people (such as me!) are going to stop continually posting questions about setup / hardware which are clearly answered in the Wiki. I KNOW there is a search facility, but it is often difficult for the newbie to know what they nead to search for!

The second thing that is needed is a few basic "getting started" guides. How to spec your hardware, that kind of thing.

This is why I started this thread and I'm glad to see I'm not alone in thinking this.

As I said earlier, I'm just starting down the MCE road myself and intend to document every step. If that becomes the basis for a HOWTO, then I'll gladly post it.

Hari, it is always difficult to get people to do this kind of work, but I'm hoping that the release of 8.10 will generate enough enthusiasm to do it. If not, the Wiki will become more and more difficult to navigate for the newbie and I firmly believe that the size of the user-base will suffer as a result.

[tschak909]

No arguments, it's just the developer base right now is so thinly stretched.

-Thom

[Techstyle]

I have added a number of pages and would contribute to a planned restructure.  I have only a little Wiki experience and about 1 years LMCE experience. 

[JaseP]

I will gladly contribute any spare time that I have (steal away from my life) to contribute to making the documentation more readable and newbie friendly... I am setting up my Core now and am actually undertaking the daunting task of trying to build LinuxMCE on top of Jaunty 9.04... No matter how futile that seems (I just think Jaunty's a better platform),...

I'll trade my time and sweat equity for increased clout as to what projects get worked on first. I have a dream for my system's functionality... I have motivated self interest pushing me to make time contributions... Hell, I converted a closet in my house to be used as a Core server closet... complete with power, shelves and ventilation. My wife wanted it for a linen closet... Do you know what that costs me?!?!?

[Techstyle]

My wife wanted it for a linen closet... Do you know what that costs me?!?!?

I think there should be a seperate thread entittled 'what LMCE cost me'.

Yes, we are all in the same boat there!!

good to have you onboard

[totallymaxed]

First up, I don't want anyone to think I'm having a dig or complaining for the sake of it. I am not starting this thread in an attempt to start a flame war or invite abuse from anyone who is feeling a tad sensitive!

I have seen various comments over the weeks (months) that I have been actively monitoring thse forums which say three things:-

1) I'd LOVE to help out more, but I'm not a developer, so I don't see how I can.
2) The documentation / wiki is less than user-friendly (usually after someone has asked a perfectly reasonable question and been told "it's in the wiki")
3) "I'm a new user, can you tell me...." (Often resulting in an impatient "do your research on the Wiki then come back....")

Like most systems that grow organically (look at most corporate shared document areas!) the Wiki has become difficult for anyone unfamiliar with it's structure to use. Of course, those of you that have been here for a long time know where to find stuff and it isn't a problem, but please put yourself in the shoes of us lessar experienced members for a moment.

If I start at the home page for MCE, I see a friendly menu titled "Wiki / Documentation ". Under here are some links, so as a regular, impatient sort of person, I click on "Quick Start" which tells me how to install the software... HOLD ON, I have no hardware yet. Ah! Let's follow the link to "Architecture Intro". This starts with

The Core

The Core has no user interface other than an administration page (unless it is a hybrid).

Unless it's a WHAT??? Maybe I need to be less impatient, so back and try "Main / Table of Contents". Hummm. Now what? Scroll down and there's promising looking sections entitled things like "Tutorials", but the indexing is not well laid out, often with what seem to arbitrary sub-sections. You get the idea.

May I suggest that (assuming anyone is still reading this) someone who falls into the "I'd love to help" category takes on the task of overhauling the Wiki? The information that is there is fantastic, but what use is that information if it can't be found? Even the search feature doesn't neccessarily help unless you know the term to search for!

Personally, I'd like to see a "OK so you're sold, you have nothing, now what" guide for idiots. There was an excellent posting on a forum recently (and my apologies to the poster as I can't recall who you were or what the thread topic was, but I did congartulate you at the time, ptobably Thom or Andrew) which described the questions you need to ask yourself and how that influences the decisions you make about your setup.

Like I said at the start, no offense is intended, particularly to whoever it was that set the Wiki up in the first place, but can we have some structure, please?

I would offer to do this myself, but I don't have my system built yet and so it really would be the "blind leading the blind".

Well my view is that your right...but the whole point of a Wiki is that anyone can contribute new articles, amend existing ones, create and manage new categorisations etc etc. To write helpful articles about LinuxMCE you need to have experience of using and configuring or writing code for it. But at the level of organising and categorising the content then i think what is needed is someone who has a clear vision of what that might be and how to achieve it...and that does not need any direct experience with LinuxMCE per-se... but a strong vision of organising information to make it accessible.

The great thing about a Wiki is that the indexing/categorisation can be overlayed on the existing articles without disruption...the editing and creation od useful new articles needs subject matter experts to get involved. Those 'subject matter' experts need to be coerced into doing some article writing and editing ;-)

All the best

Andrew

[wierdbeard65]

Hey Andrew!

Of course, you are completely correct about the Wiki overview / organisation side of things - we need an experienced librarian on board 

I guess my comments concerning experienced systems integrators come more into play when writing the initial guides. Having just found MCE, where should I start? How do I decide on kit? What are the questions I need to ask myself when deciding between Hybrid and dedicated core? etc.

The articles that are there are great (although as I have said before, in need of a compatibilty matrix) but rely on you at least having an idea of what you are trying to achieve.

The two ideas obviously are related. A better intro might reduce the need for better organisation of the articles. Similarly, better organisation may make the intro to the system less painful. Personally, I'd like to see both