A Forum User's Lament

Our MediaPortal forums are famous for the level of support they provide from 'expert' users and even MediaPortal developers. However, we often hear from users having trouble finding the information they need, or asking the same questions again and again because they can't find it.

Now that our new wiki is becoming more useful, and usage continues to increase, how can we get our forums and wiki to work together to improve support and make our forums even more effective?

The following questions and answers are extracted from discussions I had recently with a MediaPortal user rogerleifert about the relationship between our forums and wiki.

What do you think? Express yourself by posting in the comments on this Blog.

 

Why don't more forum 'experts' refer users to the MediaPortal Wiki or suggest users add good content there?

rogerleifert: Many questions (even from long-time users of MediaPortal like me) are asked over and over, but are difficult to find in the forums. That could be avoided if every expert/moderator, who has helped to answer a question or solve a problem, encourages the inquirer to add that answer/solution in the Wiki (or links to the Wiki if the answer is there already)

In the last weeks I got a lot of expert help, but until now I was the one suggesting to the experts who helped me to add something to the Wiki. It should be the other way round.

Dadeo: Some Team members (and users!) are already linking to the Wiki more often. It takes time to change old habits, but we're working on it! Remember, Team members (especially our Forum Moderators) already volunteer a lot of time and energy to MP, plus have helped to significantly increase the amount and accuracy of documentation provided, especially changes in 1.2.0. It takes a lot of time to learn everything that is in the Wiki in order to link to the appropriate page(s). 

 

Why are the 'experts' much more active in helping in the forums than in expanding the MediaPortal Wiki?

rogerleifert: I know many forums where the moderator immediately (and politely) points to the Wiki (or a simple Google search) for every question that the inquirer could answer himself. It should be in the self-interest of the moderators/experts to point the users to the Wiki.

If we could do this it would reduce the duplication and long explanations in our forums and make them far more usable.

Dadeo: As I said, I think it will happen in time. Our forums are great for specific support questions and help, but they are linear and old posts are rarely changed or updated, even Sticky posts/threads. A link to the current information in the Wiki means that anyone who is looking for it always gets the updated documentation. However, it is not only up to the 'Team' or moderators, users can also post links to relevant wiki pages which they know or contribute to, or even to user guides they add to the Wiki.

 

Why don't more users contribute to the Wiki?

Dadeo: I have noticed that many users will write 'documentation' in the forums, or add comments to Wiki pages, and spend more time than it would take to just update the wiki page, but I don't understand why! Can you explain that to me?

There is no way the Docs Group, or even all Team members, can know and document everything in MediaPortal. There are so many possible ways to configure it and as many different hardware and system configurations. Developers are already doing well documenting the changes. However, documentation of development is not enough for a good user manual. You need guides written from the user's perspective, based on their specific use case(s).

rogerleifert: I think for me (as for perhaps many other users) we are a little bit "afraid" or "shy" of editing the Wiki directly as first-timers or 'newbies' to this aspect of MP.

In Germany we also have a problem with Wikipedia. The moderators are so rigorous with Wikipedia entries that newcomers are immediately deterred and most never again try to add a new entry or make an addition.

I would have started earlier to try working with the Wiki myself, if I had gotten encouraged and (for the first time) a little bit "taken by the hand" to create my first Wiki entry or addendum.

Dadeo: I understand the shyness. I also felt the same for many years because I was never sure if my knowledge was complete or accurate enough to add to our Wiki. I also understand the 'perception' about wikis being rigorous. We had the same problem trying to update MediaPortal on Wikipedia. They kept rejecting all the changes we submitted. Thanks to the dogged determination of one of our Team members, marvman, we managed in the end! However, our Wiki is not like Wikipedia, just like MediaPortal is not like Windows Media Center. Our Wiki is a repository of all the knowledge that MediaPortal developers and users have gained over the years. The 'rules' only attempt to ensure some consistency to make it easy to use.

 

Do you find the Wiki too complex to contribute to it?

rogerleifert: As always, after you first see how easy it is, you lose your shyness and don't know why you haven't done it before. 

However, the Contributing Guide deters you. It's too complicated with too many rules. Perhaps the first entry should be "For your first entry we'll take you by the hand. Ask a Wiki-expert (Docs Group member) and he will help you with creating your first Wiki entry/correction/addendum."

When you have successfully created your first entry you are much more inclined to understand and get into the style guide 100%.

Dadeo: You're absolutely right - the Contribute to Wiki pages are more for reference rather than a guide. Like I said previously, that is not enough, a user guide is needed! We'll have to work on that! (Who said I can live up to my own ideals? LOL)

 

Why aren't all plugins documented in the Wiki? 

rogerleifert: Every plugin developer should be obliged (and constantly reminded) to create and continuously update a Wiki entry for his plugin.

On the plugin homepage there should be a direct, always visible, reminder about creating/updating the Wiki entry. At least it should encourage the thankful plugin users to create/update the Wiki page(s).

I will never understand why a developer, who should be and can be proud of his contributions, doesn't want to explain his "baby“ in all details to the community (aka Wiki) 

Dadeo: I think many developers would like to see documentation of their 'baby', but it is not always easy to document something when you are so close to it. Good documentation is usually the result of collaboration between developers, users/testers and writers. It is rare to find all the required skills in one person. Besides that, English is not the first language of many of our developers. So if you really want to see documentation of all the aspects of MediaPortal and its extensions, the only way that will happen is if more people contribute.

Everyone who works on MediaPortal donates their time and energy. We can't, and don't wish to, force anyone to do anything because MediaPortal is a labor of love.

The Plugins and Skins Downloads Repository listings already include a field for a Wiki link, which many extensions now provide. More and more extensions are adding pages to our Wiki. So we are getting there. I agree it is very helpful to include a Wiki/Docs link in the forum release post as well, although I think many extension developers do that already.

I think your idea of asking users to contribute to plugin documentation is excellent! In some cases, users have even taken over the responsibility to document plugins and in my opinion that has worked very well. It is a great way to contribute if you cannot help code or skin. If more users request documentation in the related plugin/skins forums I am sure it will happen.

Many plugins already provide their own wiki, however it would be helpful if they provided a page in our MP Wiki with an overview and link to their own wiki. At least that way there is a central index of all documentation. I see from our Wiki analysis reports that many users search for documentation of extensions - both skins and plugins - but often don't find them there.

rogerleifert: Sometimes it can even be better if the Wiki writer is NOT a developer but a user. The 'outside view' can in some places be a better approach than the 'inside view' for explaining such a complex software like MP. And a brilliant developer isn't necessarily a brilliant writer.

Nevertheless the developer is needed as a resource for the writers. So I could live with that - if the developers really concentrate on developing - as long as they are willing to support the Wiki-team to keep the Wiki up-to-date.

 

Why hasn't the Wiki been updated to 1.2.x yet since it is the latest stable/public release now?

rogerleifert: 1.2.x is now the latest stable release, so why hasn't the Wiki been updated yet?

Dadeo: There are two main reasons.

First, the Wiki already contains documentation of most of the changes made for 1.2.0. We wanted to provide a 'grace' period where we retained the documentation for 1.1.x. Not everyone has time to update right away and for some users it can be a big task depending on their setup. Version 1.2.x was a big leap in many ways, especially since all plugins and skins had to be updated as well as the extension installers (MPEI). 

The second reason is that we wish to improve the way we document new releases so you don't have all those long MP 1.2.0 notations in the text. We are already working on it and hope to propose a new process soon. Then we can implement it so that we can retain a list of all the actual changes to the user interface (UI) like we do for skin and plugin related changes.

Of course, time is always a factor when everyone is donating their spare time. When we decided to create a new skin for MediaPortal 1.2.0, our project manager, infinite.loop was very clear that the whole Team would have to help to update all screenshots in the Wiki and elsewhere. At the time we all agreed, but with the migration to GitHub, and major development already underway for 1.3.0 and for 2.0 alpha, who has time? It's the endless issue with documentation. That's why we are trying to document changes as soon as we resolve issues in Mantis, so they don't get missed. 

I would love to say that MediaPortal 1.2.0 was unique, because there were so many changes, but I am beginning to think it might be the norm now! However, hopefully we won't change the default skin too much or too often in future.

 

Do you have any suggestions how we could update the Wiki more easily and quickly?

rogerleifert: As the MP-community grows the workload in all places (developers, testers, skin-designers, docs-group) should be placed on more shoulders (='new blood'). In my view, the best place to draw new members is from the forums - IF the moderators/experts encourage new members to participate.

I remember that the Wiki at one time made a big jump forward from previously "nearly useless“ to "very helpful“. That was, in my memory, sometime between 1.1.0 and 1.2.0. alpha. I remember even an official MP news and Blog about the much improved Wiki.

Probably the enthusiasm or motivation of that time in the Wiki team has died a little down and in parallel the length of the To-Do list has increased which is of course a bit discouraging because you see the potential workload.

However, if you/we don't start NOW the workload will exponentially increase with the release of 1.3.0 alpha not to mention 2.0 alpha, where there is no user documentation yet at all.

To encourage you a bit: There are already many parts of the Wiki that are in my view nearly 100% perfect in terms of writing-style, completeness, understandability etc. At the moment it's more a case of optical "cleanliness“, logical structure or clear arrangement ( i.e. finding a relevant page with less than 3 clicks).

In my case the Wiki certainly already saved the 'experts' in the forums a lot of time because I could answer many questions myself by studying the explanations in the Wiki. However, when there is no corresponding entry with good explanations in the Wiki, everyone has to answer the same questions and problems again and again in the Forums. When a forum thread has more than 100 pages you really can't expect someone to read old forum posts for hours only to find the (already existing) answer to his problem/question.

In contrast, a positive example is the Automatic/Dynamic Refresh Rate Changer. It's in my view one of the most vital but also one of the most complex features of MP in terms of understanding it and getting it to do what it's designed for. The explanation in the Wiki: Stuttering Playback is so detailed and well written that the questions in the corresponding forum thread have dwindled down (at present the last question is more than 2 weeks old).

 

Would you like to join the Docs Group?

Dadeo: Since you have made the point so well, that we need 'new blood' would you like to join the Docs Group? You certainly seem to have the interest and motivation!

You can see an example of the new User Guide style in the My Films Wiki which we are hoping to implement in sections of the Wiki. The new Avalon Wiki has also adopted this style. I can give you access to a sample Music Users' Guide we are currently working on as well.

rogerleifert: Yes, thank you! I can help with documentation in my spare-time. But I'm afraid that I cannot follow the forums regularly to provide links to all users!

I only can say WOW. You guys set the standard quite high. It nearly scares me how well the new User Guides are organized and how well they are written because I don't know if I can contribute in this "high-end" style 

For my part, in the beginning I would like to polish up and complete the Wiki in its current style. I am particularly interested to improve the TV-Server and Radio Configuration pages, and to develop a 'Display Guide' : Display and graphics-adapter setup

Dadeo: Thanks rogerleifert that would be great! Guess who gets to write the new Wiki Contributor's user guide? 

rogerleifert: 

 

(As our newest Docs Group Team member, rogerleifert has already edited more than 235 pages, including adding many new pages with valuable content that was previously missing! Many thanks and welcome aboard!)