Structure of the XBMC Online Manual (wiki)

[neeltje57]

Hello everyone,

I am using XBMC for many years (2 modded xbox's) and now i am using it on a PC with a 46Inch LCD. I am a big fan of XBMC and was afraid it would die together with the XBOX-hardware. I am glad i was wrong. I wanted to contribute to this community and put in a few hours already with updating the manual.

I visited the manual a few times before but, although there was a lot of information in it, i got lost each time because i could not recognize the structure in it. I thought that must be easier to do and i made a table of contents (toc) on each page.

I probably made a mistake by not holding this against the team members (that is what rwparris told me in the #xbmc channel, i should do).

So here i am. I think i already did a bang up job, but that is ofcourse me. Some pages are locked so they don't have the same look and feel with an easy toc on the right side. If you like this approach please unlock the pages or give me the proper authority to edit them.

There is still a lot of work to do because the manual is wrapped around the old xbox, no offence, and there are more flavours these days. Some stuff is outdated, double, or in the wrong place when you use a toc.

Please give me your gentle opinion.

neeltje57

[jmarshall]

We appreciate the effort, but yes, before doing widespread changes, please discuss first - we have a team of people who work on and have plans for the manual and thus discussion prior to doing massive reorganisation is useful, if only to avoid stepping on toes.

I personally don't see the need for the TOC of the entire manual on the right, but I can see how it might help some - particularly if the whole thing was organised in a more cohesive manner.

For instance, I think we still need a "local" TOC on many of the longer pages, and a consistent style in this respect is better than anything.

Perhaps you could outline exactly how you see the entire manual organisation and look being done, and we can then get a discussion going from there.

Cheers,
Jonathan

[neeltje57]

Yes, i understand, me bad :). I did not know how this all worked, but here i am now. On the other hand when you start talking about something everyone has to say something and in the end nothing will change ever ...

The idea is simple though. If you don't have a toc or otherwise a straightforwarded pdf-like manual you get lost, especially when you are new. And new-ones are the target of a manual.

So the toc must be something like:
-Introduction
-Installation
-User manual
-Advanced
-Development
-Appendixes

Beside that, a more explicit division, when appropriate, for the different flavours there are (linux, Mac, Windows, Live). When you see the current toc i made, without knowing anything about xbmc, you already get an idea about how it is structured, i think. and browsing the manual is much easier. Maybe not for the experienced users who know where to look but i am pretty sure for the newbies.

Thank you for your gentle response,

neeltje57

[sho]

I agree, to the uninitiated, it's probably a huge multi-dimensional spider web.
About the only thing I miss from the old Wacko Wiki (shiver) was the convention of always showing where you came from, that is partly solved by your approach.
(With Mediawiki you can use the "what links here" as a substitute, but the likelyhood of these being used by the average casual reader are minimal).

The layout is surely all over the place, the oldest pages show that they were moved from the old wiki, restructuring ideas and help are more than welcome

But I also noticed that in some instances you removed the page toc while adding the inline main toc, was that intentional? Because I am not sure that is a good way going forward.

While I appreciate your work and input, please run things by us before undertaking anything major (or even minor to begin with).
I am very sporadically on IRC, so this would be the preferred venue.

PS What pages are locked besides the "front" pages?

[althekiller]

I agree, to the uninitiated, it's probably a huge multi-dimensional spider web.

I must still be uninitiated :(

TheUni has a pretty good plan for what the wiki needs to be IMO (I may have influenced him just a wee bit ;)). Maybe the three of you should get together on IRC and get on the same page before taking things further?

[rwparris2]

Agree with all:
-A global TOC is useful, but the one you've added now is large and still daunting imo (a collapsible tree menu would be awesome)

-The page-spefic TOC is nearly always useful and shouldn't be removed

-What I've seen of theuni's changes were well done. Perhaps a wiki-team is in order if the plan is a proper restructuring.

EDIT: This could help with not getting lost: http://www.mediawiki.org/wiki/Extension:BreadCrumbs2
EDIT2: this would actually be even better: http://www.mediawiki.org/wiki/Extension:TreeAndMenu

[theuni]

I spent a few nights hacking away at the front page to get some organization, but was quickly overburdened by the size of the task. Surely some help would be appreciated.

I've setup a temp wiki on my own server to do some big changes and get some ideas. I originally had the intention of redoing the whole thing, but I quickly realized that wouldn't be possible in my lifetime.

IMO, if we changed the front page to something sane, eliminated the xbox references, and changed the sections to something more user-centric (focusing on someone who has no idea how xbmc works, rather than hammering them with code and xml) it would go a long way.

neeltje57, if you're interested, send me a pm and we'll go from there. We need to keep the big changes off the live wiki until they can be reviewd by the rest of the team.

Thanks for your interest. Trust me, it's a bigger project than you realize :-)

TheUni

[neeltje57]

Thank you all for your responses. I agree to the approach of bringing big changes in this forum, this is the last time i apologize for being bad :). But i was invited to update the wiki on the first page of that same wiki. Maybe i took it too literal.

-I also noticed that in the bigger pages the local toc was very handy and i was already putting it back.

-The locked pages i found so far:
http://xbmc.org/wiki/?title=Introduction
http://xbmc.org/wiki/?title=Team_XBMC_and_Others
http://xbmc.org/wiki/?title=Frequently_Asked_Questions
http://xbmc.org/wiki/?title=Troubleshooting
http://xbmc.org/wiki/?title=HOW-TO_write_plugins_for_XBMC
http://xbmc.org/wiki/?title=Disclaimer
http://xbmc.org/wiki/?title=Thanks

-I think i do release how much work it is to make a nice looking manual. It will probably take me a few months or even more, if you let me. I though have no intention of changing the real content of the pages i don't even know what it is about. I am more a user, no developer. But even the pages i don't understand must have the same look and feel.

-The approach of Breadcrumbs or the TreeAndMenu look very promissing, i will try that out (don't worry, no one will see it before you all agree, haha) and come back to this place later.

-theuni, I will come back to this place before i make more big changes, and i am more than glad with help from this forum. I don't know how far you are with a mirror wiki, i think it is well possible to do this in a live environment, then you don't miss the newest updates too.

-Beside the current wiki, i am sure that there is a lot of information in this forum too, which should be brought into the wiki. There are also lost pages in the wiki, which should be brought back, i assume.

Thank you all so far, i have to rush now to go to work.

neeltje57.

[rwparris2]

> http://xbmc.org/wiki/?title=HOW-TO_w...ugins_for_XBMC (http://xbmc.org/forum/../wiki/?title=HOW-TO_write_plugins_for_XBMC)
your toc is already in there, definitely not locked :)

[althekiller]

Most of those pages shouldn't even be in the wiki IMO but on the webpage. The info in them is reasonably static and the users have business changing them. FAQ and the plugins thing aside of course.

[theuni]

I though have no intention of changing the real content of the pages i don't even know what it is about. I am more a user, no developer. But even the pages i don't understand must have the same look and feel.


I have a bit of a problem with that approach.

Part of what makes the wiki so unwieldy is a lack of structure and continuity. Lots of articles need to be moved/removed, and many more need to be updated/cleaned. For that reason, I don't see the point of patching something that needs to be overhauled. That's why I'm working on reorganizing the content so that someone new to XBMC can not only find what they're looking for, but also not be intimidated by what they find.

That said, if you'd like to help create a uniform layout, go for it. But know that much of it is bound to be reworked in the future.

I do think that we can help eachother if you're interested, though as I said before, I'd rather keep any big changes off the live wiki (temporarily) until they've been agreed upon.

TheUni

[neeltje57]

I installed a mediawiki myself (another version though, xbmc is running version 1.12.0, the current version is 1.14.0) on my own site to test the TreeAndMenu stuff. It looks promising. This may take a few days to work it out, but i will be back with the results and let you be the judge of it.

If i judge the posts you all wrote right, there are more people who want the manual be changed somehow. It is probably not a problem to put all the stuff in one manual as long as it is clear what information is for who. Newbies will probably not dive into a chapter called Development and be disappointed they don't understand it.

rwparris2: You are right about http://xbmc.org/wiki/?title=HOW-TO_write_plugins_for_XBMC. That page is not formatted to fit on a normal page though, that took me by surprise, the toc was there for sure, only a mile to the right,outside my monitor :). There are a few more pages not formatted right.

neeltje57

[neeltje57]

theuni: I posted my last post before i red yours. I am more than willing to cooperate with your approach. Our ideas look a lot the same and i am sure we can cooperate. I want to reorder a lot of stuff as well and give everything an overall look and feel everyone will like. I can not write about stuff i don't understand, that is what i mean with not wanting to change the real content. At least i need the help of the community to get that done. What i do understand i can change.

I am diving into this tree stuff anyway, because i like to learn that stuff and maybe we will need that knowledge. Can you give me more information about how far you are? And what your plan is? I don't know how it works in this community and if we do all the discussion in this forum or we email or go on irc?

I think you can email me via this forum? Please let me know.

neeltje57

[althekiller]

I'd be giddy if the wiki looked/behaved like wikipedia when you guys were done. Everyone can use it and has, no sense changing what works and is extremely intuitive.

[sho]

I'd be giddy if the wiki looked/behaved like wikipedia when you guys were done.How so?

[sho]

Please when you move / delete pages, do not leave dead links (can be seen with "What links here" on the bottom of each page).

[neeltje57]

I tried the TreeAndMenu but that did not look better. It also didnot show where you are in the manual. I think the current toc i made is not a bad idea. It is easy to maintain, it shows where you are, gives an overall view of the manual and gives newbies a guide through the manual. It doesnot look bad but if you like, it is easy to change. I tested it with 4 different browsers (ie6,ie7,firefox 3,chrome 1) the hard one was ie6, that is why i didnot use bullet lists because ie6 made big indents.

If you agree to this approach, please unlock the locked pages or change them yourself so everything will look the same.

Also keep in mind that we all will never get a manual we all will like for 100%. It is a compromise.

I will continue to update the manual in a way it is supposed to be. Some pages are outdated and should be updated, others are in the wrong place and will be moved to the appropriate place, and new ones need to be made. This may take some time, but i am not in a hurry. I hope you will like the end-result.

I think a manual can never look like wikipedia because its nature is different.A manual is often read from the start to get acquainted with a product and wikipedia is questioned just when a question pops up.

Another bonus might be that if the manual is easy you don't get so many questions from people who did not RTFM. I red a post about this in this forum.

neeltje57

[sho]

I must still be uninitiated :(Well, someone, somewhere along the way decided it was a good move to port the old Wiki manual to mediawiki trying to maintain the old structure.
Thus we end up with stuff like this:
http://xbmc.org/wiki/?title=XBMC_Online_Manual#General_Usage
and
http://xbmc.org/wiki/?title=General_Usage
and
http://xbmc.org/wiki/?title=Default_Controls
and
http://xbmc.org/wiki/?title=The_User_Interface

And some even deeper layers that neeltje57 has made redundant, giving an already overly complex spider web an exponential kick in the butt.

Trust me, I know how you feel.

TheUni has a pretty good plan for what the wiki needs to be IMO (I may have influenced him just a wee bit ). Maybe the three of you should get together on IRC and get on the same page before taking things further?I will be available after the 15th of this month.

[neeltje57]

I am not sure how i should interpret sho's last post, but it is probably not a compliment for the work i did. Or do i misunderstand it completely?

The mentioned pages were already in the wiki and a lot of pages were and are linking to them. That was not something i changed, that was already in the wiki. And i don't know anything about an old wiki, all pages are in the current wiki.

As you can see, the wiki is getting a recognizable structure already. That is a lot of work but i am still convinced it is worth it and i am sure most of you will agree that it is already easier to navigate the wiki than it was before (beside the locked pages, and a few badly formatted pages).

It is a work in progress, it must be done while the store is open. Beside the structure i updated/added some content too. When all pages are in the toc, i will concentrate more on the content itself. A lot is outdated or Xbox specific, but you can't blame me for old stuff already in the wiki. It would be nice to read what you guys think of the work i did so far.

Until you guys stop me, i keep on going for the better wiki.:)

neeltje57

[sho]

Trust me it was as close to an compliment as I ever will give ;)

No, I merely stated that you have flattened some of the lower layers of the hierarchy, that must be a good thing.
It was the "others" that did the bad things.

PS. Check out the revert I did on the Video bookmarks page, I think you may have confused video bookmarks and media bookmarks (ie sources)
Which was exactly the reason media bookmarks were changed to media sources.
If the misunderstanding is mine, please get back.

[neeltje57]

Ok, sorry for misunderstanding, i am dutch heh:).

Another thing:

In http://www.xbmc.org/wiki/?title=Adding_Media_Sources#Adding_Source_Shortcut s_to_Media_Windows Adding Media Sources (GUI) there is a paragraph which is probably not valid anymore, at least i could not find it in the PMIII skin. Please let me know if i am right, than i will remove that:

Adding Source Shortcuts to Media Windows
The default Project Mayhem III skin has the ability to add shortcut buttons pointing to sources to the left hand side menu in various sections. To enable this feature, go to the Source page in the Skin Settings. Note: The label you enter must match the label of the source.
neeltje57

[sho]

Yup, shortcuts are dead.

[Gamester17]

Yup, shortcuts are dead.hmm, are you sure, I think one can still enable them from within the skin settings :eek:

...I am sure that I have setup one for "Games", one for "Emulators", one for "Apps", and one for "Utilities"

[sho]

Have you checked?
Not to be found in my RC1 installation.

[Gamester17]

Have you checked?
Not to be found in my RC1 installation.Did you install on Xbox? ...I've not had time to update myself

[neeltje57]

I need some help in making decisions. For the last few weeks i am busy updating the manual, for now, especially the structure.

Not all pages fit in one toc, so i splitted that in a second toc (advanced, FAQ's, Inner workings and Appendixes), although i myself would not mind one large toc. Whith one large toc you see immediately where you are in the manual and it is easier to maintain. What do you think?

During my reading of the manual i learned more about XBMC from pages i didnot see before. Some very interesting pages are hard to find so i brought them into the toc. In my opinion every page should be linked somehow to the toc. That way everyone knows to find it and you find it back again easier.

But, you cannot put every page in the toc, that will make it a mess too, especially with the HOW-TO-pages. So i made for some pages a 'GoTo button'. This way, when you surf out of the toc-structure, there is always a way to go back to that toc where you were before. It is a kind of browser back-button but in the same place as the toc and it brings you to the logical place in the toc, you don't feel lost. Here is an example: http://www.xbmc.org/wiki/?title=XBMC_9.04_Point_Release

There should be a kind of strong advice that tells you that a page should be in the toc or have a GoTo-button to a page that is in the toc. It is also a waste of good information (and our time) if the average visitor will most likely not see all the pages we all made.

Please let me know what you think of this.

neeltje57