New LinuxMCE Documentation

[mcefan]

We're in the process of improving the documentation.
Please help us list the things that you  wish you knew early, things you now realize that were not so intuitive, and things you feel we should know.
In addition to the above, help us pinpoint what's missing in the documentation.

Thank you.

[bongowongo]

The problem in the wiki, there is lack of uniformity.
Also old information is not updated.
 
It is a little bit of a mess. I tried to clean it up a little bit, but it is a very big task and needs a long breath.
If you are willing to help, please do.

[mcefan]

I already started.
Please propose (describe) a standard page with look and feel, and I will create a template for new pages.
As long as people are willing to answer questions, I can clean up. I need people to work with me by letting me know if it's OK to archive some of these pages. I would also need to make sure the new info is complete. Please follow this thread and answer any question you might have answer for.
For now, I just need a less restrictive account, I'm having problems editing existing pages.

[twodogs]

Mcefan,

There was a push a while back to clean up the wiki. FWIW, I'll give you my vision of how to improve things. First, we have a single starting point - the "favorites" navigation bar categories seem ideal for this. Second, we get some Subject Matter Experts (SMEs) to take responsibility for each category. Third, the SMEs find all wiki articles relating to their subject, and create links to the favorites page. Fourth, the SMEs solicit new wiki articles to fill in the holes. Fifth, we delete all other wiki trees and structures to prevent duplication of effort and misplaced articles.

Twodogs

[Marie.O]

Twodogs,

instead of deleting I suggest marking them as obsolete, except if they are false.

[JaseP]

I agree with Posde. Deleting an article may remove useful information, however obscure. Marking them as obsolete is better.

A similar thing happened to the MythTV wiki some time ago. Out of date information was removed. Basically, that eliminated the only available documentation on a small handful of hardware pieces,... available anywhere. Once that kind of information is lost, it's pretty much lost for good... as in Library of Alexandria lost...

As far as I've seen, the Wiki has a variety of "skins" that can be applied, from the basic default, to different layout and color schemes. So, it seems like some "theme" work has already been done. And, most people expect a wiki to look/work much like Wikipedia, by default at least. So, that kind of thing doesn't seem, to me at least, to be too big a priority.

I think the key is better indexing/organization, followed by edits for readability/simplicity and organization within the articles. Among the things that need more clarity for new users from the outset are; Networking structure & how-to, Basic system architecture (how the various software pieces fit together), Simple step-by-step tutorials for the most basic functionality, and a possibly a table for hardware compatibility (with links to the relevant articles and how-tos). It might be helpful to grade articles in terms of technical level (something like; basic, intermediate, advanced, expert & developer).

Before I started working on something else, I did a few very basic edits (some basic readability/updating, and starting a glossary page). I can do some things in a spare moment, or two, as well. My plate is pretty full, but wiki editing is/can be kind of a mind clearing diversion...

[mcefan]

So far, I gather that these need to be addressed:

• updates
• removal of obsolete articles
• editing for readability/simplicity
• new users centered additions (such as Networking structure & how-to, Basic system architecture, Simple step-by-step tutorials for the most basic functionalities)
• technical level centered organization (basic, intermediate, advanced, expert & developer)
• categorization, indexing/organization
• a table of hardware compatibility connecting to corresponding linked articles
• consistent favorites navigation
• uniformity, standardization of articles

I will keep updating this list (probably on the wiki - it's more appropriate - check my user page http://wiki.linuxmce.org/index.php/User:Mcefan).

Please give the reasoning behind your suggestions so that everyone understands the issue.
If you would like to help in any of the above, please specify it.

Thank you.

[mcefan]

I updated "Contributing to LMCE" to reflect the ongoing discussion.

[mcefan]

To resolve the archival of old articles, we can simply move them to another namespace called "old articles".
I posted a page about it in the help namespace: http://wiki.linuxmce.org/index.php/Help:Namespace
There is enough information on that page for everyone.

[mcefan]

There is an old 2010 proposal called "LinuxMCE.Org 2.0" here: http://wiki.linuxmce.org/index.php/LinuxMCE.Org_2.0

Suggestions are:

Purpose
The purpose of the new site is to provide a friendly, approachable face for LinuxMCE to new users. It must:

    - Provide links to understandable descriptions of the software
    - Present a user-friendly image of the site
    - Present a pleasing aesthetic to augment the above two requirements
    - Provide project news that affects users
    - Provide a way to easily download the software
    - Provide entry to the Forums
    - Provide entry to the Wiki for detailed documentation

Menu Structure (and links to the copy pages)
    - News
    - About
    - Documentation
    - Forum
    - Download
    - Contact Us

Proposed Color Scheme
   - Text: #000000
   - Highlight: #123456

I integrated it to the list on my user page.

[mcefan]

The talk page of the above document has a few requests:

There are many problems with the site.

1) It has been written in terrible English -- misspelled words abound and proper grammar is nearly non-existent. For example, "survailance" should be "surveillance". (A simple dictionary goes a long way.)

2) Only a small portion of the program is actually documented.

3) The changes in the program are not documented and "legacy" instructions are left on the page.

4) There is a lot of "fluff" in the documentation that is meaningless. You can't write "the program can do this and this and this!!!" when only one person has ever been able to do it. Hyperbole misleads the users.

Still, the Wiki is evolving in the right direction, slowly.

It the intent is to correct the main page, then you should get some help from the contributors to the Wiki.

I worked documenting code for an American defense contractor -- the problems with LinuxMCE documentation are not unique. Most programmers are terrible at documentation.

If you want good documentation, you must have a dedicated documenter and one programmer to whom the documenter can ask questions.

I integrated it to the list on my user page.

[mcefan]

Created a new "Add a page to the wiki" and "Help:Hyperlinks".
There is enough information now to enable people to edit the pages properly.

[mcefan]

Found previous discussion on the topic at http://forum.linuxmce.org/index.php/topic,11910.0.html and http://forum.linuxmce.org/index.php/topic,11924.0.html
I will integrate these concerns in the list.



There needs to be a person in charge of verifying content added. Even if no one actually read all the articles, there needs to be a way for users to notify us of errors in documentation.
Who do people contact if they follow a procedure and find out it does not work?


To avoid having to duplicate information and create unreasonably numerous links, we really need section transclusion extensions. With that, we can create general articles from which we can select sections to include in several others articles without having to rewrite them. It will also help in keeping consistency.
There is no way to keep it clean with too many duplications.

The issue of version can be resolved by adding version categories to each page: [[category:0810]] [[category:general]] [[category:...]]
and making these categories subcategories of [[category:versions]].
This will give people the ability to navigate by drilling relevant versions.

[mcefan]

I am having problems putting things in place and I do not want to duplicate content.
Please install the following extension: http://www.mediawiki.org/wiki/Extension:Labeled_Section_Transclusion ASAP so I can continue. I'm stuck on many pages.
Also, see about changing my access level at least for 30 days so I can help in the categorization. Too many pages will not enable to add the categories. I can't save the pages.

Thank you!

[twodogs]

instead of deleting I suggest marking them as obsolete, except if they are false.

Point taken. Perhaps I mis-spoke. We should keep the content (marking obsolete as necessary), but I still think we need to delete a lot of the wiki's maze-like structure. I often find it easier to find wiki articles from a Google search "LinuxMCE black screen" or whatever. Good info on a particular piece of hardware might be found by looking at the main page of the wiki under "Hardware", but maybe the info is in "Tutorials/Guides" or the "User Manual", or the FAQ, or maybe its floating around in the wiki at large.
The frustrated user then asks a question in the forums, where a frustrated Thom complains (rightly so) that he has answered that question a thousand times.

Here is what I like to see happen. A new user want to build up a hybrid core. He clicks on "Core & Hybrid" from "Favourites" on the wiki main page. Here he sees a general overview on building a core followed by links to major components (motherboard, cpu, gpu, faqs, etc). All the info he needs is right there.

Our wiki is about as unfriendly as it can be. Want to know how to set up a RAID? Go to tutorials, but don't expect it to be under "R" - its under "C" for "Create RAID". Want to learn about PXE boot? Don't look at "P" - its under "G" fro "GRUB PXE network boot"