LinuxMCE Forums

General => Developers => Wiki => Topic started by: mcefan on September 29, 2012, 05:46:56 am

Title: New LinuxMCE Documentation
Post by: mcefan on September 29, 2012, 05:46:56 am
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.
Title: Re: New LinuxMCE Documentation
Post by: bongowongo on September 29, 2012, 09:00:40 am
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.
Title: Re: New LinuxMCE Documentation
Post by: mcefan on September 29, 2012, 02:31:50 pm
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.
Title: Re: New LinuxMCE Documentation
Post by: twodogs on September 29, 2012, 04:02:27 pm
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
Title: Re: New LinuxMCE Documentation
Post by: Marie.O on September 29, 2012, 04:25:55 pm
Twodogs,

instead of deleting I suggest marking them as obsolete, except if they are false.
Title: Re: New LinuxMCE Documentation
Post by: JaseP on September 29, 2012, 05:50:46 pm
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...
Title: Re: New LinuxMCE Documentation
Post by: mcefan on September 29, 2012, 08:03:49 pm
So far, I gather that these need to be addressed:

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.
Title: Re: New LinuxMCE Documentation
Post by: mcefan on September 29, 2012, 08:28:26 pm
I updated "Contributing to LMCE" to reflect the ongoing discussion.
Title: Re: New LinuxMCE Documentation
Post by: mcefan on September 30, 2012, 01:49:16 am
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.
Title: Re: New LinuxMCE Documentation
Post by: mcefan on September 30, 2012, 02:19:07 am
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.
Title: Re: New LinuxMCE Documentation
Post by: mcefan on September 30, 2012, 03:50:06 am
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.
Title: Re: New LinuxMCE Documentation
Post by: mcefan on September 30, 2012, 07:44:26 am
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.
Title: Re: New LinuxMCE Documentation
Post by: mcefan on September 30, 2012, 08:06:18 am
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.
Title: Re: New LinuxMCE Documentation
Post by: mcefan on September 30, 2012, 08:34:41 am
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!
Title: Re: New LinuxMCE Documentation
Post by: twodogs on September 30, 2012, 02:43:24 pm
Quote
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"
Title: Re: New LinuxMCE Documentation
Post by: Marie.O on September 30, 2012, 06:09:40 pm
whenever I go to the wiki, I don't browse, I search. So searching for PXE and/or RAID does return the right information.
Title: Re: New LinuxMCE Documentation
Post by: mcefan on September 30, 2012, 09:51:54 pm
whenever I go to the wiki, I don't browse, I search. So searching for PXE and/or RAID does return the right information.
There are several ways people acquire information.
People do not intuitively "search" when they get on a site. Instead, they "browse".
Information should be acquired in a progressive manner. Since you "own" the information, people expect you to lead them. Besides, when starting from scratch, how could you expect me to know what to search for? You post assumes I now what PXE is! What's that?
Also, even if I pull the right pages from an excellent search (assumes I got lucky typing the right terminology and the articles actually use the same words), what tells me that I am looking at the right information, and not missing something? I can search if I know: searches are based on pre-existing knowledge. Incomplete, but never the less, pre-existing.

Have you noted this from twodogs:
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.
When people have to navigate away from your site and use google to find what's on the very site they are on, I'd say you have a problem: searches don't work. They don't, because things are not organized. You can not find info in a folder by searching another...

If you want a larger user base, you can not make any assumption. All blanks, including the "obvious" ones, must be filled. The best documentations are the ones that cover all user levels, from ignorant to creator.

Navigation is vital to a site. Most people get frustrated and quickly quit when there is no logical progression to follow, or when things are not simple, or when things are difficult to find. The reason why frequently accessed pages are included in shortcut menus is to give the most common starting points. People explore, and tend to take note of the related elements, and explore those also. That's why you make things available by sight.

I suggest some reading on the subject of information architecture, it will help the venture.



What about my requests?
Title: Re: New LinuxMCE Documentation
Post by: mcefan on September 30, 2012, 10:08:03 pm
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"

Well, it looks like you have a good handle on this problem. Why not rename the pages when you encounter that? You can do that by using the "move" tab on top of the page, and rename the article.

Which brings us to naming conventions.
When naming articles, as much as possible, start with a noun. This should be obtained from answering the question "what/who is it about"?
Once the subject matter is properly identified, we need to specify the action or characteristic at addressed in the article.

Example:
what/who is it about: booting
action or characteristic: from network - PXE
resulting title: booting from network - PXE

This will keep all boot related articles within proximity:

booting
booting locally
booting remotely
booting from network
booting from network - PXE
...

It makes it easier to place the articles in the right categories afterwards (when necessary).
The key is to identify the subject accurately.
Title: Re: New LinuxMCE Documentation
Post by: mcefan on October 01, 2012, 03:32:15 am
Finding presupposes knowledge: knowledge of the location of what you are looking for.
To find it, you have to look for it where it is.

I created the following article to help with the thinking process:

Title: Re: New LinuxMCE Documentation
Post by: mcefan on October 02, 2012, 05:18:28 pm
Who is the admin responsible for the configuration of the wiki?
We need some extensions in order to clean the clutter.
Title: Re: New LinuxMCE Documentation
Post by: bongowongo on October 02, 2012, 07:36:53 pm
Who is the admin responsible for the configuration of the wiki?
We need some extensions in order to clean the clutter.

Dear mcefan,

I see a lot of knowledge and drive from your side. That is very admirable. Probably you know more about the wiki than me.
But we have to take into account your are fairly new to us. Wouldn't it a good idea to come into the IRC channel of the wiki #linuxmce-wiki @ irc.freenode.net. We can discuss some very interesting things you are posting. Please give an list of extensions/plugins you would like to see added and why.
Title: Re: New LinuxMCE Documentation
Post by: mcefan on October 03, 2012, 08:54:28 pm
I'll meet you there!
Title: Re: New LinuxMCE Documentation
Post by: mcefan on October 06, 2012, 01:41:55 am
The current documentation reads:

Offset: This causes the Orbiter to do backflips while reciting a poem backwards. (Just kidding. If you know what it does, please edit this section).

I need to replace that sentence. What does the option refer to?
Title: Re: New LinuxMCE Documentation
Post by: Marie.O on October 07, 2012, 09:59:39 am
Offset is defined in our wiki under the av wizard iirc